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

# Assessment Links

> Push candidate assessment links to Alex the moment they are generated, for immediate in-channel delivery to the candidate

## Introduction

The Assessment Links API lets an assessment provider push each candidate's unique assessment link to Alex the moment it is generated. Alex matches the link to the candidate's application and delivers it in the candidate's conversation channel (e.g. WhatsApp) within seconds.

The contract is deliberately thin: the payload carries an **opaque ATS identifier and the link** — no names, email addresses, phone numbers, scores, or results. Alex resolves candidate details and assessment outcomes from the customer's ATS directly, so a misrouted or replayed request never exposes personal data.

<Warning>
  This endpoint is **under development**. The contract below is a draft shared
  for integration scoping and may change until the integration is confirmed.
</Warning>

<Note>
  Unlike the rest of this reference, this endpoint lives under the `/v2` base:

  ```http theme={null}
  POST https://api.alex.com/v2/api/assessment-links
  ```
</Note>

## How it fits the assessment flow

The provider's existing ATS integration is unchanged — this endpoint adds one push, at the moment the link is generated:

1. The candidate is moved to the assessment stage in the ATS, which triggers an assessment order to the provider — the existing trigger, unchanged.
2. The provider generates the unique, candidate-and-job-specific assessment link, as it does today.
3. The provider writes the link (and later, results) back to the ATS — the existing write-back, unchanged.
4. **New:** at the same moment, the provider `POST`s the link to this endpoint.
5. Alex matches the `applicationId` to a candidate conversation and delivers the link in-channel within seconds. Links for applications Alex doesn't manage are discarded on receipt and not retained.
6. Completion status and scores flow back to the ATS exactly as today — Alex reads assessment status from the ATS to follow up with candidates who haven't completed. No assessment results ever pass through this API.

## Authentication

Requests are authenticated with the **customer's** API key — the same key used for the rest of the Alex API. The key determines which customer account the links apply to; a provider integrating on behalf of multiple customers holds one key per customer.

```http theme={null}
"X-API-Key": <CUSTOMER-API-KEY>
```

The provider does not need to know which of the customer's candidates Alex manages: send **every** link generated for the customer's account, and Alex matches on the application identifier and silently discards the rest.

## Pushing an assessment link

Call once per generated link, immediately after generation — ideally in the same step that writes the link back to the ATS, never on a batch or polling schedule. Candidates are typically in a live conversation when the assessment is ordered, and delivery is expected within seconds of generation.

**Request fields:**

| Field           | Description                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `applicationId` | **Required** — the ATS application identifier for the candidate–job pair (see the matrix below).                     |
| `assessmentUrl` | **Required** — the unique, candidate-specific assessment link (HTTPS). Delivered to the candidate verbatim.          |
| `candidateId`   | Optional — the ATS candidate ID, used only as a consistency cross-check.                                             |
| `jobId`         | Optional — the ATS job ID, used only as a consistency cross-check.                                                   |
| `orderId`       | Optional — the provider's own order or reference ID, included in Alex's logs for mutual traceability during support. |

**Identifier requirements by ATS:**

| ATS             | `applicationId`                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| SmartRecruiters | The application ID from the assessment order — the same identifier the provider receives when the order is placed. |

<Note>
  The `applicationId` is the routing key: it must uniquely identify the
  candidate *on a specific job*. A candidate ID alone is not sufficient — one
  candidate can hold several applications.
</Note>

<Warning>
  **Do not send candidate PII.** Names, email addresses, phone numbers, scores,
  and report data are intentionally excluded from this contract — Alex resolves
  the candidate from the ATS using the identifiers above.
</Warning>

**Example request:**

```json theme={null}
{
  "applicationId": "7f3a1c9e-4b2d-4e8a-9c61-2d5f8b0a7e14",
  "assessmentUrl": "https://assessments.example.com/start?token=Zk9x...",
  "orderId": "ORD-102938"
}
```

**Response — `200 OK`:**

```json theme={null}
{
  "success": true
}
```

A `200` is returned whether or not the application is one Alex manages — the provider does not need to distinguish, and an unmatched link is not an error.

Requests are idempotent per `applicationId`: re-sending the same payload is harmless, and sending a new link for the same application replaces the previous one (last write wins). It is always safe to retry a request you are unsure was received.

## Response codes

| Code  | Meaning                                                                                        | Retry?                 |
| ----- | ---------------------------------------------------------------------------------------------- | ---------------------- |
| `200` | Link accepted. Delivery to the candidate happens asynchronously after the response.            | —                      |
| `400` | Malformed request — missing or invalid `applicationId` / `assessmentUrl`, or a non-HTTPS link. | No — fix the request.  |
| `401` | Invalid or missing API key.                                                                    | No — fix the key.      |
| `5xx` | Transient failure on the Alex side.                                                            | **Yes**, with backoff. |

On network failure, timeout, or a `5xx` response, retry with exponential backoff (for example 30s, 2m, 10m, then hourly for up to 24 hours). Suggested client timeout: 10 seconds — the endpoint acknowledges quickly and delivers asynchronously.

## Volume

There is no rate limiting at expected volumes; if sustained throughput above \~10 requests/second is anticipated, give the Alex team a heads-up during onboarding.