---
name: unified-assessment
description: >-
  Build assessment and background-check products that plug into Applicant
  Tracking Systems (Workable, Ashby, Greenhouse, and more) through the single
  Unified.to Assessment API. Use when a coding task involves publishing
  assessment packages to an ATS, receiving assessment orders via webhooks, and
  submitting results back so recruiters see them inside their ATS.
license: MIT
metadata:
  category: assessment
  api_base: https://api.unified.to
  docs: https://docs.unified.to/assessment/overview
---

# Build a candidate assessment product with the Unified.to Assessment API

The Unified Assessment API lets assessment and background-check providers plug
into ATS platforms that expose an assessment API. Recruiters request assessments
without leaving their ATS; your product receives the order, delivers the
assessment, and pushes results back — all through one API. This skill teaches an
agent how to build against the Unified Assessment API.

## When to use this skill

Use this skill when the task is to build an assessment provider that:

- Publishes assessment packages that recruiters can pick inside their ATS
- Receives assessment **orders** when a recruiter requests an assessment
- Delivers the assessment to the candidate and computes results
- Submits scores/status back to the ATS

This is provider-side: the ATS initiates orders. (For reading candidates and
jobs from an ATS, use the `unified-ats-jobboard` skill instead.)

## How the flow works

1. Your product exposes assessment **packages** (name, price, configuration)
   that the ATS displays to recruiters.
2. A recruiter selects a package for a candidate inside their ATS. This creates
   an **order** containing candidate, job, and application details.
3. Unified.to delivers that order to you via a **webhook** (no polling).
4. You deliver the assessment to the candidate and score it.
5. You **update the order** with results (score, status, completion time), and
   they appear back inside the recruiter's ATS.

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**.
2. An assessment-only connection to a supported ATS (separate from a standard
   ATS integration) — start in the Sandbox.
3. A **connection ID** for that connection.
4. A **webhook** subscribed to assessment `order` events.

Keep the API key server-side only.

## Core request pattern

```
https://api.unified.to/assessment/{connection_id}/{object}
```

Authenticate every request:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `api.unified.to` (NA), `api-eu.unified.to` (EU),
`api-au.unified.to` (AU).

## Data objects

| Object    | Purpose                                                        |
| --------- | -------------------------------------------------------------- |
| `package` | An assessment package you offer (name, price, configuration)   |
| `order`   | An order placed by a recruiter for a candidate + its results   |

### Supported operations

| Method   | Path                                | Description                        |
| -------- | ----------------------------------- | ---------------------------------- |
| `GET`    | `/assessment/{cid}/package`         | List packages                      |
| `GET`    | `/assessment/{cid}/package/{id}`    | Get one package                    |
| `POST`   | `/assessment/{cid}/package`         | Create a package                   |
| `PATCH`  | `/assessment/{cid}/package/{id}`    | Update a package                   |
| `DELETE` | `/assessment/{cid}/package/{id}`    | Delete a package                   |
| `PATCH`  | `/assessment/{cid}/order/{id}`      | Update an order with results       |
| `PUT`    | `/assessment/{cid}/order/{id}`      | Replace an order with results      |

Orders are created by the recruiter in the ATS and delivered to you by webhook —
you update them; you do not create them.

## Example: publish a package, then submit results (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// 1. Publish an assessment package the ATS can show to recruiters
await fetch(`${BASE}/assessment/${connectionId}/package`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        name: 'Frontend Skills Assessment',
        description: 'HTML/CSS/JS take-home, ~45 min',
    }),
});

// 2. When your webhook receives an order, deliver the assessment, then
//    submit the result back against that order id.
async function submitResult(orderId, { score, status }) {
    await fetch(`${BASE}/assessment/${connectionId}/order/${orderId}`, {
        method: 'PATCH',
        headers,
        body: JSON.stringify({
            status,            // e.g. 'COMPLETED'
            score,             // provider-defined score
            completed_at: new Date().toISOString(),
        }),
    });
}
```

Consult the order and package data models for exact fields:
https://docs.unified.to/assessment/order/model and
https://docs.unified.to/assessment/package/model.

## Receiving orders via webhook

Register a webhook for the assessment `order` object so orders reach you in real
time. See https://docs.unified.to/reference/webhooks and
https://docs.unified.to/concepts/virtual_webhooks. On receipt:

1. Verify and parse the order payload (candidate, job, application, package).
2. Kick off your assessment delivery flow.
3. When done, `PATCH` the order with results (see example above).

## Official SDKs

```bash
npm install @unified-api/typescript-sdk
```

SDKs for TypeScript, Python, PHP, Java, Go, C#, and Ruby:
https://docs.unified.to/reference/sdks.

## Error handling

| Code | Meaning & action                                            |
| ---- | ----------------------------------------------------------- |
| 401  | Connection broken — re-authorize.                           |
| 403  | Missing scopes — fix provider app + Unified.to scopes.      |
| 429  | Provider rate limit — back off and retry.                   |
| 501  | Operation unsupported by the ATS — check Feature Support.   |

## References

- Assessment API overview & data model: https://docs.unified.to/assessment/overview
- Webhooks: https://docs.unified.to/reference/webhooks
- REST basics: https://docs.unified.to/reference/rest
- Source guide: https://docs.unified.to/guides/how_to_build_a_candidate_assessment_product_with_unified