How to Offer Assessment Packages and Receive Orders with Unified's Assessment API

February 19, 2026

Assessment providers increasingly need to integrate directly into Applicant Tracking Systems (ATS) so recruiters can request assessments without leaving their hiring workflow.

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
Support multiple ATS platforms through a single integration

This is not a status-trigger workflow.

This is a recruiter-initiated, embedded integration model.

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

Supported ATS platforms (assessment integrations):

Ashby Assessment
Cornerstone Assessment
Greenhouse Assessment
Recruitee Assessment
TalentLyft Assessment
Workable Assessment

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

Mental Model: Embedded Assessment Integration

With the Assessment API:

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 sends you an assessment_order webhook.
You process the assessment.
You submit results via the order update endpoint.
The results appear inside the ATS.

The recruiter never leaves 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/assessment/{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

Required fields

id
name
type

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[] — availability restrictions
cost_amount and currency
processing_time

These determine how the ATS displays your package and what information it collects.

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:

HMAC signature
nonce
Retry mechanism (3 immediate retries + Fibonacci backoff)
Event type indicators (INITIAL-PARTIAL, INITIAL-COMPLETE, etc.)

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: