2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

How to Use the Unified Assessment API

February 9, 2026

Overview

The Unified Assessment API allows assessment and background check providers to seamlessly integrate with Applicant Tracking Systems (ATS) platforms. This API enables recruiters to request assessments for candidates directly from within their ATS, streamlining the hiring process.

How This Differs from the Unified Verification API

The Unified Verification API is designed for any software application to call assessment and verification software providers that are provided by Unified. In that flow, the application initiates requests to verification providers through Unified's Verification API using the unified data-models.

How This Differs from the Unified ATS API

The Unified ATS API allows for assessment software application to listen to job applications and trigger an assessment/test/check when that application reaches a specific status. This flow is great for those ATS vendors that do not offer an 'Assessment API', and thus support most of the ATS integrations on Unified.to.

The new Unified Assessment API works in a different way: it connects directly into ATS "assessment APIs" and allows recruiters inside those ATS platforms to request assessments for candidates. Those requests then get communicated to the assessment applications, which then trigger an assessment/test/check. Once those tests are complete, they call the Unified Assessment API and update that assessment order, which would then get communicated back to the ATS.

This new Unified API allows recruiters to stay inside their ATS and not need to use another 3rd-party application's interface to request candidate assessments.

For Assessment software providers, the new Unified Assessment API is preferable as is has less friction for recruiters, but is limited by the number of supported ATSs. For all of the other ATSs, you will still need to use the traditional ATS flow outlined above.

Supported ATS Integrations

Currently, the Unified Assessment API supports the following ATS platforms:

  • Greenhouse
  • Ashby
  • Workable

Each integration has a new assessment-only integration that is separate from their ATS-only integration.

Getting Started

Step 1: Create a Connection

First, you need to manually create a connection for your assessment integration. This connection will be used to authenticate requests from the ATS.

When creating the connection, you must supply a Partner API Key in the connection.auth.token field that you generate yourself. You will then share this API key with your end-customer to configure the integration in their ATS.

Always check the authentication requirements for each assessment integration as some will require additional authentication information. For example, Ashby also requires a Customer API Key and a Partner ID.

Example Connection Creation:

{
  "integration_type": "greenhouseassessment",
  "auth": {
    "token": "YOUR_PARTNER_API_KEY"
  },
}

Step 2: Configure Webhooks

You also need to set up webhooks to receive assessment orders from the ATS systems.

Required Webhook

Create a webhook with the following configuration:

  • object_type: assessment_order
  • event: created

This webhook will be triggered whenever a recruiter requests an assessment for a candidate in the ATS.

Optional Webhook

Some ATS vendors (like Ashby) also send order cancellation events. You can optionally create an additional webhook:

  • object_type: assessment_order
  • event: deleted

This webhook will notify you when an assessment order is cancelled.

Step 3: Provide Configuration to Your End-Customer

Once you've created the connection and webhook, provide the following information to your end-customer:

  1. Base URL: https://api.unified.to/assessments/{connection_id}
    • Replace {connection_id} with the actual connection ID from Step 1
  2. Partner API Key: The token value you set in connection.auth.token

Your end-customer will then input these credentials into their ATS software to enable the integration.

Workflow Overview

Here's how the assessment flow works:

  1. Package Configuration: You create assessment packages via the Unified API (w/ assessment packages API endpoints)
  2. ATS Lists Packages: The ATS queries your available packages
  3. Recruiter Orders Assessment: A recruiter selects a package and orders an assessment for a candidate
  4. Webhook Notification: Unified.to sends you a webhook with the order details
  5. Process Assessment: You send the assessment to the candidate and process their response
  6. Submit Results: You submit the assessment results back to Unified.to (w/ assessment order update API endpoint)
  7. Results in ATS: The results appear in the ATS for the recruiter to review

API Endpoints

Assessment Packages

Manage your available assessment packages:

  • POST /assessment/{connection_id}/package - Create a new package
  • GET /assessment/{connection_id}/package - List all packages
  • GET /assessment/{connection_id}/package/{id} - Get a specific package
  • PUT /assessment/{connection_id}/package/{id} - Update a package
  • DELETE /assessment/{connection_id}/package/{id} - Delete a package

Assessment Orders

Update assessment order results:

  • PUT /assessment/{connection_id}/order/{id} - Update an order with results

Webhook Payload

When an assessment order is created, you'll receive a webhook with an AssessmentOrder payload:

{
  "id": "123",
  "package_id": "your_package_id",
  "candidate": {
    "candidate_id": "candidate_456",
    "email": "candidate@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1 123 456 7890"
  },
  "application": {
    "id": "application_789"
  },
  "job": {
    "id": "job_012",
    "name": "Software Engineer",
  },
  "status": "OPEN"
}

Submitting Results

Once a candidate completes an assessment, submit the results using the update order endpoint:

PUT /assessment/{connection_id}/order/{order_id}

Example Request:

{
  "status": "COMPLETED",
  "score": 85,
  "max_score": 100,
  "result_url": "<https://your-platform.com/results/order_123>",
  "completed_at": "2024-01-15T10:30:00Z",
  "attributes": [
    {
      "type": "TEXT",
      "label": "Overall Assessment",
      "value": "Strong candidate"
    }
  ]
}

The results will then be written back to the ATS system, where recruiters can view them directly.

Best Practices

  1. Secure Your API Key: Treat your Partner API Key as sensitive information. Only share it with trusted end-customers.
  2. Handle Webhooks Reliably: Implement retry logic and idempotency checks in your webhook handler to ensure you don't miss or duplicate orders.
  3. Validate Webhook Data: Always validate the webhook payload to ensure it contains the expected candidate and job information before processing.
  4. Monitor Order Status: Track the status of assessment orders and handle cancellations appropriately when the deleted event webhook is received.

Support

For questions or issues with the Unified Assessment API, please contact our support team or refer to the Unified.to Documentation.

All articles