The invitation object
| Field | Type | Description |
|---|---|---|
id | string | The invitation's id |
candidateId, interviewId | string | Who is invited, to what |
interviewTitle | string | The interview's title when invited |
status | string | invited, opened, started, completed or expired |
expiresAt | date-time | The last moment the link opens the interview |
openedAt, startedAt, completedAt | date-time or null | When each step happened |
sessionId | string or null | The interview session, once started: use it for results |
externalId | string or null | Your own id, given when inviting |
returnUrl | string or null | Where the candidate goes after finishing |
skipSignIn | boolean | Created with skipSignIn: the link alone signs the candidate in |
opensAt | date-time or null | With nycNotice: the interview can't start before this; null: it can start now |
revokedAt | date-time or null | When it was revoked (its status then reads expired); null for one that simply ran out, and again after a resend |
emailStatus | string or null | The invitation email: pending (not sent yet, or being retried), sent, refused (the address was refused for good) or bounced (it bounced, was marked as spam or the address is suppressed); null once the candidate started |
createdAt | date-time | When it was created |
Invite a candidate
/v1/invitationsScope invitations:write| Body field | Type | Description |
|---|---|---|
candidateId | string, required | A candidate of your company |
interviewId | string, required | A published interview of your company |
expiresInDays | integer | 1 to 60. Default: your company's link expiry (Settings → General, 7 days unless you changed it) |
returnUrl | string | An https URL. When the candidate finishes (outside the embed) the finished screen shows a "Back to <your company>" button to it |
skipSignIn | boolean | Default false. You already signed the candidate in on your own site: the link alone signs them in, without the code we email. See below |
externalId | string | Up to 200 characters: your id for this invitation (a job application, a requisition). Comes back on the invitation and in every webhook |
nycNotice | boolean | Default false. The candidate lives in New York City: the email carries your AEDT notice (set in the dashboard) and the interview opens 10 business days later (opensAt); 400 while you have no notice |
extraTime | integer | 0 (default), 25, 50 or 100. Extra time for a candidate who asked for it (an accommodation): every time limit grows by this percent. An interview runs at most 60 minutes, extra time included: a share that would take it longer (+50% on a 45-minute interview, any on a 60-minute one) is a 400 with the reason. The candidate sees the longer times without a label; your reviewers see "Extra time +50%" on the results. Recorded in your audit log and never returned by the API or sent in webhooks. Change it later on the invitation's page in the dashboard, until the candidate starts; ATS invitations get it there too |
- The link is shown once. We email it to the candidate as well. Hand it to the embed SDK to run the interview on your own site.
- Refusals:
404Candidate not found or Interview not found;400Publish the interview before inviting candidates;402when your plan has no interview minutes left. - Accepts
Idempotency-Key.
Skip the sign-in code
By default the candidate proves they own the invited email with a one-time code. When your own site has already signed the candidate in, send skipSignIn: true and the link alone opens the interview, whatever your company's email check setting is. Only an API key with invitations:write can set it; the dashboard can't.
- Embed: show the embed only on a page your candidate reaches after signing in to your site, and hand it the link.
- Redirect: send the signed-in candidate from your site straight to the link.
- The link becomes the key. Anyone who has it can take the interview, so keep
expiresInDaysshort (1 or 2), never put the link in a URL others see, and create the invitation when the candidate is about to start. We still email it to the invited address. - Recorded: the invitation shows
skipSignIn: true, the session'sconsent.identityVerifiedByiscompany, and your audit log notes that sign-in was skipped.
List invitations
/v1/invitationsScope invitations:readNewest first. Takes limit and cursor, and filters that combine:
| Query parameter | Description |
|---|---|
candidateId | Only that candidate's invitations |
interviewId | Only invitations to that interview |
externalId | Only the invitations you gave that externalId (an exact match): find the invitation of a job application again |
status | invited, opened, started, completed or expired: the status the invitation shows. expired includes invitations never started whose expiresAt has passed, and revoked ones |
An invalid filter is a 400 with issues. A cursor continues only the list with the filters it came from.
Get an invitation
/v1/invitations/{id}Scope invitations:readThe invitation's current status and, once the candidate started, its sessionId.
Revoke an invitation
/v1/invitations/{id}/revokeScope invitations:writeWhen the application was withdrawn or the candidate declined: the invitation ends now. Every link stops working, reminders stop, and it reads as expired. No body. Answers 200 with the invitation. Safe to repeat: a revoked invitation comes back unchanged. Your audit log names the API key.
- Refusals:
404Invitation not found;409The candidate has already started this interview.
Resend an invitation
/v1/invitations/{id}/resendScope invitations:writeA new link replaces every old one, which stop working, and we email the candidate again. Answers 200 with the invitation and the new link, shown once. An expired or revoked invitation gets a new deadline; one still open keeps its own unless you send expiresInDays.
| Body field | Type | Description |
|---|---|---|
expiresInDays | integer | 1 to 60: the new link's days. Default: an expired invitation gets your company's link expiry; an open one keeps its deadline |
- Each call makes a new link and sends another email. Send an
Idempotency-Key: a retry with the same key gets the first answer again. - Refusals:
404Invitation not found;409The candidate has already started this interview;409This interview was deleted, so the invitation can't be sent again;429(rate_limited, withRetry-After) after five resends of one invitation within an hour, from the dashboard and the API together.