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.

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

Unlike the rest of this reference, this endpoint lives under the /v2 base:

POST https://api.alex.com/v2/api/assessment-links

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 POSTs 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.

"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.

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.

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.

Example request:

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

Response — 200 OK:

{
  "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.