How to build a Candidate Assessment product with

Updated: October 23, 2026

October 23, 2023

There are two ways to build a candidate assessment product on your customers' ATS. In the first, your product reads applications through Unified.to's ATS API, starts an assessment when an application reaches a status you choose, and writes the result back to the candidate record. It needs no ATS partnership and works on any ATS integration that returns applications. In the second, your packages are listed inside the ATS's own assessment module and recruiters order them there; Unified.to's Assessment API handles that route on ATSes with an assessment module (see How to Offer Assessment Packages and Receive Orders). This guide covers the first route.

The same data can feed AI screening or semantic resume matching; see the RAG section at the end.

Who is this guide for?

It's for teams with a candidate assessment product (skills tests, background checks, structured interviews) who need to read new applications from their customers' ATS and return results to it.

Read new applications from your customers' ATS (applicant tracking system) so your product can assess those candidates.
Retrieve resumes and job descriptions to power RAG-based candidate ranking and semantic matching.

Unified.to's ATS API covers 164 ATS integrations, including Greenhouse, Lever, SmartRecruiters and SAP SuccessFactors (full list).

How to add ATS integrations to your product

Before we start, be sure to first read:

Getting Started with Unified.to

Get an initial list of applications

When the customer authorizes an ATS connection, read the initial set of applications for a job (filtering by job_id and updated_gte where the integration supports them)

import { UnifiedTo } from '@unified-api/typescript-sdk';
import { AtsApplication, AtsApplicationStatus } from '@unified-api/typescript-sdk/sdk/models/shared';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

export async function getApplications(connectionId: string, trigger_status: AtsApplicationStatus, jobId: string, updatedGte?: string) {
    const applications: AtsApplication[] = [];
    const limit = 100;
    let offset = 0;

    while (true) {
        // listAtsApplications returns the array of applications directly
        const apps = await sdk.ats.listAtsApplications({
            updatedGte, // ISO-8601 string, e.g. '2026-10-01T00:00:00Z'
            jobId,
            offset,
            limit,
            connectionId,
        });

        applications.push(...apps.filter((application) => application.jobId === jobId && application.status === trigger_status)); // job_id is honoured server-side on some integrations only

        if (apps.length === limit) {
            offset += limit;
        } else {
            break;
        }
    }

    return applications;
}

Set up to get updated applications

To receive new and updated applications, create a webhook for that connection_id. Application webhooks are native or virtual depending on the integration; virtual webhooks check at an interval you set, as often as every minute on paid plans, and a check that finds nothing isn't billed. Check the integration page for which applies.

import { createHmac, timingSafeEqual } from 'crypto';
import { UnifiedTo } from '@unified-api/typescript-sdk';
import { AtsApplicationStatus, Webhook, WebhookEvent, WebhookObjectType, WebhookType } from '@unified-api/typescript-sdk/sdk/models/shared';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

// The payload arrives as JSON with snake_case field names
interface IncomingWebhook {
    id: string;
    created_at: string;
    updated_at: string;
    workspace_id: string;
    connection_id: string;
    hook_url: string;
    object_type: string;
    interval: number;
    checked_at: string;
    integration_type: string;
    environment: string;
    event: 'created' | 'updated' | 'deleted';
    runs: string[];
    fields: string;
    webhook_type: WebhookType;
    is_healthy: boolean;
    page_max_limit: number;
}

interface IncomingApplication {
    id: string;
    candidate_id?: string;
    job_id?: string;
    status?: AtsApplicationStatus;
    original_status?: string;
    updated_at?: string;
}

interface IWebhookData<T> {
    data: T[]; // The data array contains objects of the webhook's object type (eg. ATS applications)
    webhook: IncomingWebhook; // The webhook object
    nonce: string; // random string
    sig256: string; // base64(HMAC-SHA256(workspace.secret, JSON.stringify(data) + nonce))
    external_xref?: string; // the external_xref you set on the connection
    type: 'INITIAL-PARTIAL' | 'INITIAL-COMPLETE' | 'VIRTUAL' | 'NATIVE';
}

export async function createApplicationsWebhook(connectionId: string, myWebhookUrl: string): Promise<Webhook> {
    // createUnifiedWebhook returns the Webhook object directly
    return await sdk.unified.createUnifiedWebhook({
        webhook: {
            hookUrl: myWebhookUrl,
            objectType: WebhookObjectType.AtsApplication,
            event: WebhookEvent.Updated,
            connectionId,
        },
    });
}

export async function handleUnifiedWebhook(incoming: IWebhookData<IncomingApplication>, trigger_status: AtsApplicationStatus) {
    if (incoming.webhook.object_type !== 'ats_application') {
        return; // not for us
    }

    const secret = process.env.WORKSPACE_SECRET;
    if (!secret) {
        throw new Error('WORKSPACE_SECRET is not set');
    }

    const computed = Buffer.from(
        createHmac('sha256', secret)
            .update(JSON.stringify(incoming.data)) // must match the order and encoding received
            .update(String(incoming.nonce))
            .digest('base64'),
        'utf8',
    );
    const provided = Buffer.from(incoming.sig256 ?? '', 'utf8');
    if (computed.length !== provided.length || !timingSafeEqual(computed, provided)) {
        return; // signature mismatch: reject the payload
    }

    return incoming.data?.filter((application) => application.status === trigger_status);
}

Alternatively, create a polling schedule to get new/updated applications, which would be similar to the code in 1a)

Filter applications on a specific status
1. The application carries a standard status (with the vendor's own label in original_status), so choose the status that should start the assessment.
2. Application.Status options are NEW REVIEWING SCREENING SUBMITTED FIRST_INTERVIEW SECOND_INTERVIEW THIRD_INTERVIEW BACKGROUND_CHECK OFFERED ACCEPTED HIRED REJECTED DECLINED WITHDRAWN. Of these, REVIEWING, SCREENING, FIRST_INTERVIEW, SECOND_INTERVIEW, or BACKGROUND_CHECK should be considered.

Email the candidate with the assessment based on the job

Read the candidate from the Application.candidate_id field

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

export async function readCandidate(connectionId: string, candidateId: string) {
    return await sdk.ats.getAtsCandidate({
        id: candidateId,
        connectionId,
    });
}

Optional: read the job from the Application.job_id field

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

export async function readJob(connectionId: string, jobId: string) {
    return await sdk.ats.getAtsJob({
        id: jobId,
        connectionId,
    });
}

Determine which test to send to the candidate based on the Job.id, Job.description or Job.name fields

Once the candidate has completed the assessment/test, notify the hiring manager and/or recruiter

Read the employee from the Job.hiring_manager_ids or Job.recruiter_ids fields, on integrations that support the HR employee object on the same connection (Greenhouse and Lever do), and email them from Employee.emails

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

export async function readEmployee(connectionId: string, employeeId: string) {
    return await sdk.hris.getHrisEmployee({
        id: employeeId,
        connectionId,
    });
}

Optional: write a PDF report to the application or candidate in the customer's ATS, on integrations that support document creation (Greenhouse and Workable attach to the application; Lever to the candidate)

import { UnifiedTo } from '@unified-api/typescript-sdk';
import { AtsDocumentType } from '@unified-api/typescript-sdk/sdk/models/shared';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

// Greenhouse and Workable attach documents by applicationId; Lever, Ashby and SmartRecruiters by candidateId
export async function createDocument(connectionId: string, target: { applicationId?: string; candidateId?: string }, documentUrl: string, filename: string, type: AtsDocumentType) {
    return await sdk.ats.createAtsDocument({
        atsDocument: {
            ...target,
            type,
            documentUrl,
            filename,
        },
        connectionId,
    });
}

Optional: create an activity (a note on the candidate or application) on integrations that support it, such as Greenhouse, Lever, Workable and Ashby. Where the integration accepts scorecard creation (SmartRecruiters, Ashby, Workday and SAP SuccessFactors among them; not Greenhouse or Lever, as of 19 October 2026), you can create a scorecard instead.

Optional: update the candidate's tags on integrations where tags are writable (Greenhouse and Lever are two). Read the candidate's current tags, add yours, and send the full list, so no existing tags are lost.

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: process.env.UNIFIED_API_KEY!,
    },
});

export async function updateCandidateTags(connectionId: string, candidateId: string, newTags: string[]) {
    // read the current tags and send the merged list, so no existing tags are lost
    const candidate = await sdk.ats.getAtsCandidate({
        id: candidateId,
        connectionId,
    });

    return await sdk.ats.updateAtsCandidate({
        atsCandidate: {
            tags: [...new Set([...(candidate.tags ?? []), ...newTags])],
        },
        id: candidateId,
        connectionId,
    });
}

Write-back targets vary by ATS (as of 19 October 2026): activities (notes, created on 55 integrations) and documents (48) are the widest options, application status is writable on 33 of 125 application integrations, and scorecards can be created on the fewest (12, not Greenhouse or Lever). Check the integration page before you design around one.

Advanced: Adding RAG-Based Resume Matching

Beyond triggering assessments, you can use the same data for retrieval-augmented generation (RAG):

Subscribe to application created and updated webhooks so new resumes are embedded as they arrive.
Retrieve the candidate's resume (an ats_document with type RESUME) and the job's description.
Chunk and embed both documents.
Store embeddings in your vector database with identifiers like connection_id, candidate_id, job_id and updated_at.
Retrieve the most relevant resume segments against the job description before generating screening insights or ranking scores.

Unified.to reads the ATS data at request time and returns it in one schema across ATS integrations, with no customer records at rest; embeddings and retrieval stay in your infrastructure.

Keep learning

How do you start?

Connect a test ATS, list its applications and register an application webhook; the steps above are the whole integration. Start a 30-day free trial or book a demo.

Are we missing anything? Let us know

Was this page helpful?