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 integrate directly with Applicant Tracking Systems (ATS) platforms that support embedded assessment listings.

This API enables recruiters to request assessments for candidates directly from within their ATS. The recruiter does not need to log into a separate assessment platform or manage a second interface.

Instead, the assessment package is selected inside the ATS, and the request is routed to your platform through Unified.

This is different from triggering assessments based on status changes. It is a recruiter-initiated flow inside the ATS itself.

How This Differs from the Unified Verification API

The Unified Verification API is used by ATS or HRIS platforms to call verification or assessment providers in a unified way.

In that flow:

  • The ATS or HRIS platform initiates the request.
  • They do not need a direct partnership with the assessment provider.
  • The call is routed through Unified using the unified verification data models.

The Assessment API is different.

It is designed for assessment providers who want their assessment packages listed directly inside an ATS that supports embedded assessment integrations.

The direction of integration is reversed.

How This Differs from the Unified ATS API

The Unified ATS API allows assessment providers to listen for job application changes and trigger an assessment when an application reaches a specific status.

That flow works across most ATS platforms supported by Unified and does not require a special assessment marketplace integration.

It is best suited for ATS platforms that do not support embedded assessment listings.

The new Unified Assessment API works in a different way:

  • It connects directly to ATS platforms that have a dedicated 'assessment API.'
  • Your assessment packages are listed inside the ATS.
  • A recruiter manually selects a package for a candidate.
  • The ATS sends an assessment order through Unified.
  • You process the assessment.
  • You update the order.
  • The results are written back into the ATS.

The key difference:

The recruiter stays inside the ATS the entire time.

There is no external trigger based on status change. The recruiter explicitly orders the assessment.

When Should You Use Each?

For assessment providers:

  • Use the Assessment API when the ATS supports embedded assessment listings and you have a partnership with that ATS.
  • Use the ATS API for all other ATS platforms.

Most providers will use both:

  • Assessment API for supported ATS platforms.
  • ATS API as the broad coverage fallback.

The Assessment API reduces recruiter friction but is limited to ATS platforms that expose this functionality.

Supported ATS Integrations

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

  • Greenhouse
  • Ashby
  • Workable

Each of these has a dedicated assessment integration that is separate from the standard ATS integration.

Only ATS platforms that support embedded assessment listings can be supported through this API.

Expansion to additional supported ATS platforms is ongoing.

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