---
title: "How to Embed Assessments in ATS Platforms with"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_embed_assessments_in_ats_platforms_with-icon.png
date: 2026-02-19T23:32:00.000Z
updated: 2026-10-21T11:26:50.146Z
readingTime: 5
tag: Product
description: "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..."
url: "https://unified.to/blog/how_to_embed_assessments_in_ats_platforms_with"
---

# How to Embed Assessments in ATS Platforms with

<iframe width="560" height="315" src="https://www.youtube.com/embed/m9vlaZdv7GM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>


[Unified.to](http://unified.to/)'s [Assessment API](/assessment) 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](http://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](/blog/replacing_polling_with_event_driven_integrations_using_virtual_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](https://unified.to/blog/how_to_build_a_candidate_assessment_product_with_unified).


## What This Use Case Covers


This guide explains how to:

1. Create an assessment integration connection
2. Publish assessment packages
3. Receive recruiter-initiated assessment orders
4. Process and update assessment results
5. 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](https://docs.unified.to/assessment/integrations).


Each of these uses an assessment-specific integration type that is separate from the standard [ATS API](/ats).


## How does the embedded assessment flow work?


Seven steps, and the recruiter never leaves the ATS:

1. You create assessment packages via Unified.
2. The ATS lists your packages inside its interface.
3. A recruiter selects a package and orders an assessment for a candidate.
4. [Unified.to](http://unified.to/) sends you an `assessment_order` webhook.
5. You process the assessment.
6. You submit results via the order update endpoint.
7. 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:


```plain text
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


```plain text
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)


```typescript
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


```plain text
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:


```plain text
POST /unified/webhook
```


Example configuration:


```json
{
  "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:


```json
{
  "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:

1. Validate webhook signature
2. Store the order in your system
3. Issue the assessment to the candidate
4. Track completion

Order status lifecycle:

- `OPEN`
- `IN_PROGRESS`
- `COMPLETED`
- `FAILED`
- `REJECTED`

## Step 5: Submit Results Back to ATS


When assessment is complete:


```plain text
PUT /assessment/{connection_id}/order/{order_id}
```


### Example


```typescript
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](https://docs.unified.to/assessment/integrations).


## 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](http://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](http://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](https://unified.to/blog/how_to_build_a_candidate_assessment_product_with_unified))

**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](https://unified.to/blog/6_assessment_apis_to_integrate_with_in_2026_greenhouse_workable_ashby) covers what each one requires.


[→ Start your 30-day free trial](https://app.unified.to/login)


[→ Book a demo](https://calendly.com/d/cph9-g8n-jzg/connect-with-unified)