> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Onboarding

> Enroll candidates into Agentic Onboarding flows, track step progress, sync external statuses, track offer documents, and retrieve verified documents, report PDFs, and signed offer PDFs

Agentic Onboarding automates post-offer candidate onboarding—document collection, background verification, and pre-employment medical testing. You enroll candidates into a configured **flow**; TapTalent handles candidate communication, document upload with OCR extraction, resubmission loops, and verification, and notifies your systems via webhooks at each verified milestone. All requests use the base path `/v1/partner/onboarding`.

**Authentication:** `Authorization: Bearer YOUR_API_KEY`—see [API Keys](/authentication/api-keys).

Related: webhook setup and delivery are described in [Webhooks Overview](/webhooks/overview); the full event payloads are in [Agentic Onboarding events](/webhooks/events#agentic-onboarding-events).

<Info>
  By default, your own integration layer consumes these APIs and webhooks and performs the corresponding actions in your system of record (candidate document upload, document tagging/categorization, candidate status moves). As a managed alternative, TapTalent can also deliver this data directly into your HRIS—see [HRIS Delivery Options](/technical-integration/hris-delivery).
</Info>

## Concepts

| Term                      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flow**                  | A configured onboarding process with ordered steps. Step `stepKey` values: `doc_collection`, `pre_employment_medical_test`, `background_verification`.                                                                                                                                                                                                                                                                                                                                                                 |
| **Onboarding candidate**  | A candidate enrolled in one flow, identified by `onboardingCandidateId`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **`overallStatus`**       | Candidate-level status: `not_started`, `in_progress`, `partial_submission`, `under_review`, `final_handoff`, `completed`, `rejected`, `failed`, `terminated`.                                                                                                                                                                                                                                                                                                                                                          |
| **Step progress**         | Per-step status: `pending`, `in_progress`, `submitted`, `verified`, `rejected` (with `rejectionReason` and `verifiedAt` where applicable).                                                                                                                                                                                                                                                                                                                                                                             |
| **Journey link**          | A secure tokenized URL where the candidate completes their onboarding tasks and uploads documents (max 10 MB per file, 30 files per batch). The link stops resolving once the enrollment reaches `terminated`, `rejected`, or `failed`. Treat it as sensitive.                                                                                                                                                                                                                                                         |
| **`externalRef`**         | Your correlation ID (e.g. a candidate or requisition ID from your ATS/HRIS) supplied at enrollment and echoed in responses and webhook events.                                                                                                                                                                                                                                                                                                                                                                         |
| **Reports and documents** | Always PDFs. APIs and webhooks return time-limited PDF URLs—download promptly and re-fetch via the documents endpoint when a URL has expired.                                                                                                                                                                                                                                                                                                                                                                          |
| **Offer documents**       | Offer letters are TapTalent **e-signature documents**—prepared and sent from the dashboard, identified by `offerId`, and linked to a candidate through signer records (`candidateId`/`jobCandidateId`). Document status: `draft` → `in_progress` → `completed` (the only three). Per-signer status: `pending` → `sent` → `opened` → `signed`, with `openedAt`/`signedAt` and sequential or parallel signing groups (`signingOrder`). Once completed, the final signed PDF (with audit-trail certificate) is available. |
| **Onboarding credits**    | Enrollment consumes one onboarding credit per candidate. Requests that exceed your balance fail with **402** and `{"requiredCredits": ..., "availableCredits": ...}`.                                                                                                                                                                                                                                                                                                                                                  |

***

## List Flows

Get the onboarding flows configured for your company.

### `GET /onboarding/flows`

### Query Parameters

| Parameter | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| `status`  | string | No       | Filter by flow status (e.g. `active`).    |
| `page`    | number | No       | Page number (default: 1).                 |
| `limit`   | number | No       | Results per page (default: 20, max: 100). |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/onboarding/flows?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "flows": [
      {
        "flowId": "flowId_1",
        "name": "New Hire Onboarding",
        "status": "active",
        "steps": [
          { "stepKey": "doc_collection", "stepOrder": 1, "isActive": true },
          { "stepKey": "background_verification", "stepOrder": 2, "isActive": true },
          { "stepKey": "pre_employment_medical_test", "stepOrder": 3, "isActive": true }
        ],
        "createdAt": 1234567890000,
        "updatedAt": 1234567890000
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  }
}
```

### Error Responses

* **401** – Missing or invalid API key. See [API Keys](/authentication/api-keys).

***

## Enroll Candidate

Enroll a candidate into an onboarding flow. Call this when your hiring process links a candidate to a position (for example, when your ATS/HRIS marks the candidate as ready for onboarding).

Enrollment automatically starts the pre-onboarding sequence—welcome email, keep-warm communication, attendance confirmation, orientation content, and government document collection with OCR extraction and resubmission handling. No API calls are needed for these steps.

### `POST /onboarding/flows/:flowId/candidates`

### Path Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `flowId`  | string | Yes      | Onboarding flow ID. |

### Request Body

| Field         | Type   | Required | Description                                                                                                                                            |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `firstName`   | string | Yes      | Candidate's first name.                                                                                                                                |
| `lastName`    | string | Yes      | Candidate's last name.                                                                                                                                 |
| `email`       | string | Yes      | Candidate's email address.                                                                                                                             |
| `phoneNumber` | string | No       | Candidate's phone number (E.164 format).                                                                                                               |
| `externalRef` | string | No       | Your own reference for this candidate (max 255 characters), echoed in responses and webhook events. Strongly recommended for correlation.              |
| `metadata`    | object | No       | Arbitrary key–value pairs stored with the enrollment and returned by [Get Onboarding Candidate](#get-onboarding-candidate) (`null` when not provided). |

### Request Body Example

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+639171234567",
  "externalRef": "CAND-88213"
}
```

### Example Request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/onboarding/flows/flowId_1/candidates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "externalRef": "CAND-88213"
  }'
```

### Example Response

Returns **201 Created**.

```json theme={null}
{
  "status": "success",
  "data": {
    "onboardingCandidateId": "onbCandidateId_1",
    "flowId": "flowId_1",
    "overallStatus": "not_started",
    "externalRef": "CAND-88213",
    "journeyUrl": "https://talent.taptalent.io/candidate-journey/onboarding/JOURNEY_TOKEN",
    "stepProgress": [
      { "stepKey": "doc_collection", "stepOrder": 1, "status": "pending" },
      { "stepKey": "background_verification", "stepOrder": 2, "status": "pending" },
      { "stepKey": "pre_employment_medical_test", "stepOrder": 3, "status": "pending" }
    ],
    "enrolledAt": 1234567890000
  }
}
```

### Error Responses

* **400** – Missing or invalid fields. `code`: `INVALID_REQUEST`.
* **402** – Not enough onboarding credits. `code`: `INSUFFICIENT_ONBOARDING_CREDITS`, `details`: `{"requiredCredits": 1, "availableCredits": 0}`.
* **404** – Flow not found. `code`: `NOT_FOUND`.
* **409** – An active (non-terminal) enrollment already exists for this email or `externalRef` in this flow. `code`: `DUPLICATE_ENROLLMENT`.

***

## Enroll Candidates (Bulk)

Enroll up to **100** candidates into a flow in a single request. Enrollment consumes one onboarding credit per candidate; if your balance is lower than the number of candidates, the whole batch is rejected with **402** and no one is enrolled. Credits are consumed only for candidates in `enrolled`.

One `onboarding.candidate.enrolled` webhook event fires per enrolled candidate.

### `POST /onboarding/flows/:flowId/candidates/bulk`

### Path Parameters

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `flowId`  | string | Yes      | Onboarding flow ID. |

### Request Body

| Field        | Type  | Required | Description                                                                                        |
| ------------ | ----- | -------- | -------------------------------------------------------------------------------------------------- |
| `candidates` | array | Yes      | 1–100 candidate entries. Each entry uses the same fields as [Enroll Candidate](#enroll-candidate). |

### Request Body Example

```json theme={null}
{
  "candidates": [
    { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "externalRef": "CAND-88213" },
    { "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "externalRef": "CAND-88214" }
  ]
}
```

### Example Request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/onboarding/flows/flowId_1/candidates/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "externalRef": "CAND-88213" },
      { "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "externalRef": "CAND-88214" }
    ]
  }'
```

### Example Response

Returns **201 Created**.

```json theme={null}
{
  "status": "success",
  "data": {
    "enrolled": [
      { "onboardingCandidateId": "onbCandidateId_1", "email": "john.doe@example.com", "externalRef": "CAND-88213", "journeyUrl": "https://talent.taptalent.io/candidate-journey/onboarding/JOURNEY_TOKEN_1" }
    ],
    "skipped": [
      { "email": "jane.smith@example.com", "externalRef": "CAND-88214", "reason": "DUPLICATE_ENROLLMENT" }
    ],
    "enrolledCount": 1,
    "skippedCount": 1
  }
}
```

### Error Responses

* **400** – `candidates` missing, empty, more than 100 entries, or an entry is invalid. `code`: `INVALID_REQUEST`.
* **402** – Not enough onboarding credits for the batch. `code`: `INSUFFICIENT_ONBOARDING_CREDITS`, `details`: `{"requiredCredits": 40, "availableCredits": 12}`. No candidates are enrolled.
* **404** – Flow not found. `code`: `NOT_FOUND`.

***

## Get Onboarding Candidate

Retrieve an onboarding candidate's current status, per-step progress, and journey link.

### `GET /onboarding/candidates/:onboardingCandidateId`

### Path Parameters

| Parameter               | Type   | Required | Description              |
| ----------------------- | ------ | -------- | ------------------------ |
| `onboardingCandidateId` | string | Yes      | Onboarding candidate ID. |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/onboarding/candidates/onbCandidateId_1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "onboardingCandidateId": "onbCandidateId_1",
    "flowId": "flowId_1",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "overallStatus": "in_progress",
    "externalRef": "CAND-88213",
    "externalStatus": "Offer Accepted",
    "externalEmployeeId": null,
    "metadata": null,
    "journeyUrl": "https://talent.taptalent.io/candidate-journey/onboarding/JOURNEY_TOKEN",
    "stepProgress": [
      { "stepKey": "doc_collection", "stepOrder": 1, "status": "verified", "rejectionReason": null, "verifiedAt": 1234567890000, "updatedAt": 1234567890000 },
      { "stepKey": "background_verification", "stepOrder": 2, "status": "in_progress", "rejectionReason": null, "verifiedAt": null, "updatedAt": 1234567890000 },
      { "stepKey": "pre_employment_medical_test", "stepOrder": 3, "status": "pending", "rejectionReason": null, "verifiedAt": null, "updatedAt": 1234567890000 }
    ],
    "enrolledAt": 1234567890000,
    "completedAt": null
  }
}
```

### List variant

To look up candidates by your own reference or filter by status, use:

### `GET /onboarding/candidates`

| Parameter       | Type   | Required | Description                                     |
| --------------- | ------ | -------- | ----------------------------------------------- |
| `externalRef`   | string | No       | Return candidates enrolled with this reference. |
| `flowId`        | string | No       | Filter by flow.                                 |
| `overallStatus` | string | No       | Filter by overall status.                       |
| `page`          | number | No       | Page number (default: 1).                       |
| `limit`         | number | No       | Results per page (default: 20, max: 100).       |

The response is `data.candidates[]` (same shape as above, without `stepProgress`) plus `pagination`.

### Error Responses

* **404** – Onboarding candidate not found. `code`: `NOT_FOUND`.

***

## List Candidate Documents and Reports

List the documents and reports collected or produced for an onboarding candidate. All files are PDFs, returned as time-limited URLs—re-calling this endpoint returns fresh URLs.

### `GET /onboarding/candidates/:onboardingCandidateId/documents`

### Path Parameters

| Parameter               | Type   | Required | Description              |
| ----------------------- | ------ | -------- | ------------------------ |
| `onboardingCandidateId` | string | Yes      | Onboarding candidate ID. |

### Query Parameters

| Parameter  | Type   | Required | Description                                                                                                                                |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `category` | string | No       | `government_document`, `background_verification_report`, `pre_employment_medical_report`, `medical_clearance_slip`, or `document_package`. |
| `stepKey`  | string | No       | Filter by flow step (`doc_collection`, `background_verification`, `pre_employment_medical_test`).                                          |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/onboarding/candidates/onbCandidateId_1/documents?category=background_verification_report" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "documents": [
      {
        "documentId": "documentId_1",
        "name": "Background Verification Report - Final",
        "category": "background_verification_report",
        "stepKey": "background_verification",
        "status": "verified",
        "pdfUrl": "https://cdn.taptalent.io/onboarding/onbCandidateId_1/documentId_1.pdf?signature=...",
        "extractedFields": { "reportDate": "2025-08-14", "resultSummary": "CLEAR" },
        "uploadedAt": 1234567890000,
        "verifiedAt": 1234567890000
      }
    ]
  }
}
```

| Field             | Type   | Description                                                                      |
| ----------------- | ------ | -------------------------------------------------------------------------------- |
| `status`          | string | `submitted`, `verified`, or `rejected`.                                          |
| `pdfUrl`          | string | Time-limited URL to the PDF. Download promptly; re-fetch for a fresh URL.        |
| `extractedFields` | object | Key–value pairs extracted by OCR (e.g. government ID numbers), where applicable. |

### Get a single document

`GET /onboarding/candidates/:onboardingCandidateId/documents/:documentId` returns one document in the same shape, with a fresh `pdfUrl`.

### Error Responses

* **404** – Onboarding candidate or document not found. `code`: `NOT_FOUND`.

***

## Update External Status

Push your system's hiring status for a candidate into TapTalent—typically each status movement in your ATS/HRIS up to Employee ID creation. The values are stored on the enrollment, shown to your onboarding team, and returned by [Get Onboarding Candidate](#get-onboarding-candidate).

### `PATCH /onboarding/candidates/:onboardingCandidateId/external-status`

### Path Parameters

| Parameter               | Type   | Required | Description              |
| ----------------------- | ------ | -------- | ------------------------ |
| `onboardingCandidateId` | string | Yes      | Onboarding candidate ID. |

### Request Body

| Field                | Type   | Required | Description                                              |
| -------------------- | ------ | -------- | -------------------------------------------------------- |
| `externalStatus`     | string | Yes      | Your system's status label for the candidate.            |
| `externalEmployeeId` | string | No       | The Employee ID once created in your system.             |
| `effectiveAt`        | number | No       | Unix timestamp (ms) of the status change in your system. |
| `note`               | string | No       | Free-text note stored with the update.                   |

### Example Request

```bash theme={null}
curl -X PATCH "https://partner-api.taptalent.io/v1/partner/onboarding/candidates/onbCandidateId_1/external-status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalStatus": "Ready for Hire",
    "externalEmployeeId": "EID-104233"
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "onboardingCandidateId": "onbCandidateId_1",
    "externalStatus": "Ready for Hire",
    "externalEmployeeId": "EID-104233",
    "updatedAt": 1234567890000
  }
}
```

### Error Responses

* **400** – Missing or invalid fields. `code`: `INVALID_REQUEST`.
* **404** – Onboarding candidate not found. `code`: `NOT_FOUND`.

***

## Terminate Enrollment

End an enrollment. Sets `overallStatus` to `terminated`, stops all candidate communication for the flow, and invalidates the journey link. Fires `onboarding.candidate.status_changed`.

### `POST /onboarding/candidates/:onboardingCandidateId/terminate`

### Path Parameters

| Parameter               | Type   | Required | Description              |
| ----------------------- | ------ | -------- | ------------------------ |
| `onboardingCandidateId` | string | Yes      | Onboarding candidate ID. |

### Request Body

| Field    | Type   | Required | Description                           |
| -------- | ------ | -------- | ------------------------------------- |
| `reason` | string | No       | Reason recorded with the termination. |

### Example Request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/onboarding/candidates/onbCandidateId_1/terminate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Candidate withdrew" }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "onboardingCandidateId": "onbCandidateId_1",
    "overallStatus": "terminated"
  }
}
```

### Error Responses

* **404** – Onboarding candidate not found. `code`: `NOT_FOUND`.
* **409** – Enrollment is already in a terminal state (`completed`, `rejected`, `failed`, or `terminated`). `code`: `ALREADY_TERMINAL`.

***

## List Offer Documents

List offer documents, optionally filtered to a job candidate, candidate, job, or status. Offer documents are prepared and sent for signature by recruiters from the TapTalent dashboard—this API is read-only plus notifications (creating, sending, reminding, and cancelling are dashboard-only).

### `GET /onboarding/offers`

### Query Parameters

| Parameter        | Type   | Required | Description                                          |
| ---------------- | ------ | -------- | ---------------------------------------------------- |
| `jobCandidateId` | number | No       | Return offer documents linked to this job-candidate. |
| `candidateId`    | string | No       | Return offer documents linked to this candidate.     |
| `jobId`          | number | No       | Return offer documents linked to this job.           |
| `status`         | string | No       | `draft`, `in_progress`, or `completed`.              |
| `page`           | number | No       | Page number (default: 1).                            |
| `limit`          | number | No       | Results per page (default: 20, max: 100).            |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/onboarding/offers?jobCandidateId=101&status=in_progress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "offers": [
      {
        "offerId": "offerId_1",
        "subject": "Offer Letter - Senior Software Engineer",
        "status": "in_progress",
        "jobCandidateId": 101,
        "candidateId": "candidateId_1",
        "jobId": 12345,
        "signerCount": 2,
        "signedCount": 1,
        "createdAt": 1234567890000,
        "updatedAt": 1234567890000,
        "completedAt": null
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  }
}
```

### Error Responses

* **400** – Invalid query parameters (e.g. unknown `status`). `code`: `INVALID_REQUEST`.
* **401** – Missing or invalid API key. See [API Keys](/authentication/api-keys).

***

## Get Offer Document

Get one offer document with per-signer statuses and, once completed, fresh time-limited URLs for the signed PDF and audit certificate.

### `GET /onboarding/offers/:offerId`

### Path Parameters

| Parameter | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `offerId` | string | Yes      | Offer document ID. |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/onboarding/offers/offerId_1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "offerId": "offerId_1",
    "subject": "Offer Letter - Senior Software Engineer",
    "status": "completed",
    "jobCandidateId": 101,
    "candidateId": "candidateId_1",
    "jobId": 12345,
    "signers": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "status": "signed",
        "signingOrder": 1,
        "candidateId": "candidateId_1",
        "jobCandidateId": 101,
        "openedAt": 1234567890000,
        "signedAt": 1234567890000
      },
      {
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "status": "signed",
        "signingOrder": 2,
        "candidateId": null,
        "jobCandidateId": null,
        "openedAt": 1234567890000,
        "signedAt": 1234567890000
      }
    ],
    "signedPdfUrl": "https://cdn.taptalent.io/offers/offerId_1/signed.pdf?signature=...",
    "auditTrailUrl": "https://cdn.taptalent.io/offers/offerId_1/audit-certificate.pdf?signature=...",
    "signedPdfSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "auditTrailSha256": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752",
    "expiresAt": 1234567890000,
    "createdAt": 1234567890000,
    "completedAt": 1234567890000
  }
}
```

| Field                                                | Type                              | Description                                                                                                                                                                           |
| ---------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                                             | string                            | `draft`, `in_progress`, or `completed`.                                                                                                                                               |
| `jobCandidateId` / `candidateId` / `jobId`           | number / string / number, or null | Taken from the signer linked to a job candidate; `null` when the document is not linked.                                                                                              |
| `signedPdfUrl`                                       | string or null                    | Time-limited URL to the final signed PDF (includes the audit-trail certificate). Only present when `status` is `completed`. Download promptly; re-fetch this endpoint for fresh URLs. |
| `auditTrailUrl`                                      | string or null                    | Time-limited URL to the standalone audit certificate PDF. Only present when `completed`.                                                                                              |
| `signedPdfSha256` / `auditTrailSha256`               | string or null                    | SHA-256 of each file, for integrity verification. `null` until completed.                                                                                                             |
| `expiresAt`                                          | number or null                    | Unix timestamp (ms) when the URLs expire. `null` until completed.                                                                                                                     |
| `signers[].status`                                   | string                            | `pending`, `sent`, `opened`, or `signed`.                                                                                                                                             |
| `signers[].signingOrder`                             | number or null                    | 1-based signing group; signers with the same value sign in parallel, later groups are invited after earlier groups finish. `null` when all signers sign in parallel.                  |
| `signers[].openedAt` / `signers[].signedAt`          | number or null                    | Unix timestamps (ms); `null` until that step is reached.                                                                                                                              |
| `signers[].candidateId` / `signers[].jobCandidateId` | string / number, or null          | Candidate linkage; `null` for non-candidate signers such as your countersigner.                                                                                                       |

### Error Responses

* **401** – Missing or invalid API key. See [API Keys](/authentication/api-keys).
* **404** – Offer document not found. `code`: `NOT_FOUND`.

***

## Webhook events

Configure a webhook URL in your dashboard ([Webhooks Overview](/webhooks/overview)) to receive Agentic Onboarding events. One webhook URL per company receives all events—route on the `event` field (or the `X-Webhook-Event` header).

| Event                                 | When it is sent                                                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `onboarding.candidate.enrolled`       | A candidate was enrolled into a flow (fires per candidate, including bulk enrollments).                                                |
| `onboarding.candidate.status_changed` | The candidate's `overallStatus` changed (including terminal states).                                                                   |
| `onboarding.documents.verified`       | Government documents were validated during pre-onboarding; includes PDF URLs and OCR-extracted fields.                                 |
| `onboarding.report.ready`             | A report PDF is available (background verification report—initial or final, pre-employment medical result, or medical clearance slip). |
| `onboarding.candidate.completed`      | The candidate reached `completed`; includes the final document package PDFs.                                                           |
| `onboarding.offer.completed`          | Every signer on an offer document has signed and the final signed PDF and audit certificate are ready.                                 |

For payload details, see [Agentic Onboarding events](/webhooks/events#agentic-onboarding-events). There are no per-signer webhook events—poll [Get Offer Document](#get-offer-document) for interim signer progress.

### Typical actions in your system of record

| Event                                               | Typical HRIS-side action performed by your integration                                                                  |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `onboarding.candidate.enrolled`                     | Store the `onboardingCandidateId` ↔ candidate correlation.                                                              |
| `onboarding.documents.verified`                     | Candidate document upload (validated government documents and numbers).                                                 |
| `onboarding.report.ready` (background verification) | Candidate document upload **and** document tagging/categorization of the report (initial and final).                    |
| `onboarding.report.ready` (pre-employment medical)  | Candidate document upload **and** document tagging/categorization of the result; clearance slip uploaded as a document. |
| `onboarding.candidate.status_changed`               | Candidate status move, where your process requires it.                                                                  |
| `onboarding.candidate.completed`                    | Upload the final document package; final candidate status move.                                                         |
| `onboarding.offer.completed`                        | Candidate document upload **and** document tagging/categorization of the signed offer PDF.                              |

## Integration sequence

1. Generate an API key ([API Keys](/authentication/api-keys)) and configure your company webhook URL in the dashboard ([Webhooks Overview](/webhooks/overview)).
2. When your hiring process links a candidate to a position, call [Enroll Candidate](#enroll-candidate) (or [bulk](#enroll-candidates-bulk)) with an `externalRef`.
3. TapTalent runs pre-onboarding automatically (welcome email, keep-warm communication, attendance confirmation, orientation content, government document collection with OCR and resubmission)—no API calls needed.
4. Push your status updates and the Employee ID to [Update External Status](#update-external-status) until Employee ID creation.
5. Handle `onboarding.documents.verified` and `onboarding.report.ready` events; download the PDF URLs promptly (they expire), or re-fetch fresh URLs from [List Candidate Documents and Reports](#list-candidate-documents-and-reports).
6. Your integration performs the corresponding actions in your system of record: candidate document upload, document tagging/categorization, candidate status moves.
7. On `onboarding.offer.completed`, download the signed offer PDF and audit certificate promptly (URLs expire), or re-fetch fresh URLs from [Get Offer Document](#get-offer-document), and file them against the candidate.
8. On `onboarding.candidate.completed`, retrieve the final document package and complete the hire in your system.

## Notes

<Note>
  * In the self-serve model, all writes to your system of record are performed by your own integration, using the data delivered by these APIs and webhooks. Direct delivery into your HRIS is also available as a managed option—see [HRIS Delivery Options](/technical-integration/hris-delivery).
  * There are no per-event webhook subscriptions. One company-level webhook URL receives all events; webhook configuration is dashboard-only and not available via the Partner API.
  * Reports and documents are never inlined in webhook payloads—only time-limited PDF URLs. Store TapTalent IDs (`onboardingCandidateId`, `documentId`), not URLs.
  * Internal orchestration (vendor endorsement, appointment scheduling, review queues) is handled inside TapTalent and is not exposed through this API.
  * Offer documents move only through `draft` → `in_progress` → `completed`—there is no declined, voided, or expired state. They carry no compensation terms (amount, start date) as API fields; your offer terms live in the document content itself. Creating, sending, reminding, and cancelling offer documents are dashboard-only actions.
</Note>