How to Embed Assessments in ATS Platforms with

Published February 19, 2026 · Last updated October 21, 2026

Unified.to's Assessment API lets an assessment or background-check company list its packages inside an ATS's assessment module, receive the orders recruiters place there by webhook, and write the results back to the candidate's record. It works on ATSes that run an assessment module, most of them in beta on Unified.to as of 19 October 2026.

The Unified Assessment API allows you to:

Publish assessment packages into supported ATS platforms
Receive recruiter-initiated assessment orders via webhooks
Submit structured results back to the ATS
Reach every supported ATS assessment module through the same calls

The recruiter starts the order inside the ATS; nothing triggers on application status. For the status-trigger route on ATSes without an assessment module, see How to build a Candidate Assessment product with Unified.to.

What This Use Case Covers

This guide explains how to:

Create an assessment integration connection
Publish assessment packages
Receive recruiter-initiated assessment orders
Process and update assessment results
Handle order lifecycle events

As of 19 October 2026, the Assessment API connects to the assessment modules of Ashby, ATS Anywhere, Cornerstone, Greenhouse, JobAdder, PageUp, Paylocity, Recruitee, SmartRecruiters, TalentLyft, Teamtailor and Workable. Workable Assessment is generally available; the others are in beta. It also orders assessments from assessment companies such as Berke, The Predictive Index and Wonderlic (beta). See the Assessments integration list.

Each of these uses an assessment-specific integration type that is separate from the standard ATS API.

How does the embedded assessment flow work?

Seven steps, and the recruiter never leaves the ATS:

You create assessment packages via Unified.
The ATS lists your packages inside its interface.
A recruiter selects a package and orders an assessment for a candidate.
Unified.to sends you an assessment_order webhook.
You process the assessment.
You submit results via the order update endpoint.
The results appear inside the ATS.

Step 1: Create an Assessment Connection

Unlike ATS OAuth connections, Assessment connections are manually created and authenticated using a Partner API Key.

You create a connection with:

integration_type (e.g., greenhouseassessment)
auth.token (your Partner API Key)

Your customer configures their ATS using:

Base URL: https://api.unified.to/assessments/{connection_id}
Partner API Key: <your token>

Each assessment integration may have additional authentication requirements (for example, Ashby may require additional identifiers). Always verify integration-specific auth requirements before onboarding customers.

Step 2: Publish Assessment Packages

Recruiters cannot order an assessment unless you first publish packages.

Create a Package

POST /assessment/{connection_id}/package

Which fields does a package need?

type is required. id and name are writable on every ATS assessment module; Ashby also takes description, and TalentLyft takes type, description, info_url and regions.

Valid type values:

SKILLS_TEST
BEHAVIORAL_ASSESSMENT
VIDEO_INTERVIEW
BACKGROUND_CHECK
REFERENCE_CHECK
OTHER

Example (Node SDK)

const results = await sdk.assessment.createAssessmentPackage({
  connectionId,
  assessmentPackage: {
    id: 'engineering_skills_v1',
    name: 'Engineering Skills Test',
    type: 'SKILLS_TEST',
    description: 'Backend engineering evaluation',
    max_score: 100,
  },
});

Package Configuration Fields

Key configuration fields include:

parameters[] — assessment input fields (TEXT, NUMBER, FILE, etc.)
has_redirect_url — whether candidate is redirected externally
needs_ip_address — whether IP address is required
regions[]: country or region codes, with cost_amount, currency and processing_time (milliseconds) per region

Each ATS displays only the fields its own assessment API accepts, so most of these are ignored on Greenhouse, Cornerstone and Recruitee, which take an id and a name.

List Packages

GET /assessment/{connection_id}/package

Default pagination:

limit (default 100)
offset (default 0)

Step 3: Configure Webhook to Receive Orders

Assessment orders are delivered through the standard Unified webhook system.

Create a webhook:

POST /unified/webhook

Example configuration:

{
  "hook_url": "https://your-platform.com/webhooks",
  "connection_id": "<connection_id>",
  "object_type": "assessment_order",
  "event": "created"
}

This webhook fires when a recruiter orders an assessment in the ATS.

Webhook Payload

You receive an AssessmentOrder payload:

{
  "id": "123",
  "package_id": "engineering_skills_v1",
  "candidate_id": "candidate_456",
  "application_id": "application_789",
  "job_id": "job_012",
  "status": "OPEN"
}

Additional profile fields may be included:

profile_name
profile_emails
profile_resume_url
profile_ip_address
profile_date_of_birth
etc.

Webhook delivery includes:

A sig256 signature (HMAC-SHA256 of your workspace secret, the data and the nonce)
A nonce
Retries: three immediately, then a Fibonacci backoff

Step 4: Process the Assessment

After receiving the order:

Validate webhook signature
Store the order in your system
Issue the assessment to the candidate
Track completion

Order status lifecycle:

OPEN
IN_PROGRESS
COMPLETED
FAILED
REJECTED

Step 5: Submit Results Back to ATS

When assessment is complete:

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

Example

const results = await sdk.assessment.updateAssessmentOrder({
  connectionId,
  id: 'order_123',
  assessmentOrder: {
    status: 'COMPLETED',
    response_score: 85,
    response_max_score: 100,
    response_url: 'https://your-platform.com/results/order_123',
    response_completed_at: '2026-02-19T10:30:00Z',
    response_attributes: [
      {
        type: 'TEXT',
        label: 'Overall Assessment',
        value: 'Strong technical proficiency'
      }
    ]
  }
});

The ATS displays:

Score
Completion status
Result link
Structured attributes
Download URLs (if provided)

Which result fields can you write?

The AssessmentOrder model supports:

Structured score fields
Redirect URLs
Detailed result breakdown (response_details)
Additional attributes (response_attributes)
Downloadable reports (response_download_urls)

status, response_score and response_url are writable on every ATS assessment module. response_attributes is writable on Ashby, Greenhouse, PageUp, Recruitee, TalentLyft, Teamtailor and Workable; response_download_urls on Paylocity, Recruitee, SmartRecruiters, TalentLyft and Teamtailor; response_max_score on SmartRecruiters and Teamtailor (as of 19 October 2026). Required fields are marked on each integration page.

Handling Order Lifecycle Events

If supported, some ATS integrations may issue cancellation events. If your system receives a cancellation:

Mark order as REJECTED
Stop processing
Avoid duplicate fulfillment

Always design your webhook handler to be idempotent.

Does Unified.to store assessment orders or results?

No. Order updates go to the source ATS at request time, with no customer records at rest; connection credentials and operational metadata are encrypted at rest. Your product stays the record of what each candidate scored. When the result appears to the recruiter depends on the ATS: Greenhouse, for example, retrieves it after your update and documents up to an hour before it shows in Greenhouse Recruiting.

Security Best Practices

Treat Partner API Keys as sensitive.
Validate webhook signatures.
Implement idempotent webhook processing.
Store connection_id securely.
Handle retries gracefully.

Should you use the Assessment API or the ATS API?

There are three ways to integrate assessments with Unified.to:

1. Embedded (Assessment API)

Recruiter selects assessment inside ATS
Best UX, requires ATS support

2. Triggered (ATS API)

Trigger on status change
Works on any ATS integration that returns applications (see How to build a Candidate Assessment product with Unified.to)

3. Verification-style (Verification API)

ATS/HRIS calls provider directly
No marketplace required

Use the Assessment API when:

The ATS supports embedded assessment listings.
You want recruiters to initiate assessments inside the ATS.
You have a partnership-style integration.

Use the ATS API fallback when:

The ATS does not support embedded assessment integrations.
You trigger assessments based on status changes.

Most providers will use both:

Assessment API for supported ATS platforms.
ATS API for broader coverage.

What does the Assessment API replace?

Per-ATS partner endpoints, authentication schemes, webhook formats and order models: you create packages once, receive orders by webhook and write results through one order-update call. The partnership with each ATS stays yours; 6 ATS assessment APIs covers what each one requires.

→ Start your 30-day free trial

→ Book a demo

All articles