Skip to content

API

Invitations.

An invitation asks one candidate to take one published interview, through a personal link.

Last updated 19 November 2026

The invitation object

FieldTypeDescription
idstringThe invitation's id
candidateId, interviewIdstringWho is invited, to what
interviewTitlestringThe interview's title when invited
statusstringinvited, opened, started, completed or expired
expiresAtdate-timeThe last moment the link opens the interview
openedAt, startedAt, completedAtdate-time or nullWhen each step happened
sessionIdstring or nullThe interview session, once started: use it for results
externalIdstring or nullYour own id, given when inviting
returnUrlstring or nullWhere the candidate goes after finishing
skipSignInbooleanCreated with skipSignIn: the link alone signs the candidate in
opensAtdate-time or nullWith nycNotice: the interview can't start before this; null: it can start now
revokedAtdate-time or nullWhen it was revoked (its status then reads expired); null for one that simply ran out, and again after a resend
emailStatusstring or nullThe 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
createdAtdate-timeWhen it was created

Invite a candidate

POST/v1/invitationsScope invitations:write
Body fieldTypeDescription
candidateIdstring, requiredA candidate of your company
interviewIdstring, requiredA published interview of your company
expiresInDaysinteger1 to 60. Default: your company's link expiry (Settings → General, 7 days unless you changed it)
returnUrlstringAn https URL. When the candidate finishes (outside the embed) the finished screen shows a "Back to <your company>" button to it
skipSignInbooleanDefault false. You already signed the candidate in on your own site: the link alone signs them in, without the code we email. See below
externalIdstringUp to 200 characters: your id for this invitation (a job application, a requisition). Comes back on the invitation and in every webhook
nycNoticebooleanDefault 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
extraTimeinteger0 (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
curl -X POST https://api.testee.ai/v1/invitations \  -H "Authorization: Bearer $TESTEE_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 8e0f6c1a-2b7d-4d0e-9a51-3c6f2e9b7d40" \  -d '{"candidateId":"cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f","interviewId":"iv_mh3k2p9x4f7a2c","expiresInDays":7,"returnUrl":"https://careers.example.com/thanks","externalId":"req-2291"}'
Response
{  "invitation": {    "id": "inv_mh3m8k1qz8x4pd",    "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",    "interviewId": "iv_mh3k2p9x4f7a2c",    "interviewTitle": "Backend engineer screen",    "status": "invited",    "expiresAt": "2026-11-19T10:02:44.000Z",    "createdAt": "2026-11-12T10:02:44.000Z",    "openedAt": null,    "startedAt": null,    "completedAt": null,    "sessionId": null,    "externalId": "req-2291",    "returnUrl": "https://careers.example.com/thanks",    "skipSignIn": false,    "opensAt": null,    "emailStatus": "sent",    "revokedAt": null  },  "link": "https://interview.testee.ai/i/x9Qf…"}
  • 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: 404 Candidate not found or Interview not found; 400 Publish the interview before inviting candidates; 402 when 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 expiresInDays short (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's consent.identityVerifiedBy is company, and your audit log notes that sign-in was skipped.

List invitations

GET/v1/invitationsScope invitations:read

Newest first. Takes limit and cursor, and filters that combine:

Query parameterDescription
candidateIdOnly that candidate's invitations
interviewIdOnly invitations to that interview
externalIdOnly the invitations you gave that externalId (an exact match): find the invitation of a job application again
statusinvited, 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.

curl "https://api.testee.ai/v1/invitations?interviewId=iv_mh3k2p9x4f7a2c&externalId=req-2291" \  -H "Authorization: Bearer $TESTEE_API_KEY"
Response
{  "data": [    {      "id": "inv_mh3m8k1qz8x4pd",      "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",      "interviewId": "iv_mh3k2p9x4f7a2c",      "interviewTitle": "Backend engineer screen",      "status": "invited",      "expiresAt": "2026-11-19T10:02:44.000Z",      "createdAt": "2026-11-12T10:02:44.000Z",      "openedAt": null,      "startedAt": null,      "completedAt": null,      "sessionId": null,      "externalId": "req-2291",      "returnUrl": "https://careers.example.com/thanks",      "skipSignIn": false,      "opensAt": null,      "emailStatus": "sent",      "revokedAt": null    }  ],  "nextCursor": null}

Get an invitation

GET/v1/invitations/{id}Scope invitations:read

The invitation's current status and, once the candidate started, its sessionId.

curl https://api.testee.ai/v1/invitations/inv_mh3m8k1qz8x4pd \  -H "Authorization: Bearer $TESTEE_API_KEY"

Revoke an invitation

POST/v1/invitations/{id}/revokeScope invitations:write

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

curl -X POST https://api.testee.ai/v1/invitations/inv_mh3m8k1qz8x4pd/revoke \  -H "Authorization: Bearer $TESTEE_API_KEY"
Response
{  "id": "inv_mh3m8k1qz8x4pd",  "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",  "interviewId": "iv_mh3k2p9x4f7a2c",  "interviewTitle": "Backend engineer screen",  "status": "expired",  "expiresAt": "2026-11-14T09:30:00.000Z",  "createdAt": "2026-11-12T10:02:44.000Z",  "openedAt": null,  "startedAt": null,  "completedAt": null,  "sessionId": null,  "externalId": "req-2291",  "returnUrl": "https://careers.example.com/thanks",  "skipSignIn": false,  "opensAt": null,  "emailStatus": "sent",  "revokedAt": null}
  • Refusals: 404 Invitation not found; 409 The candidate has already started this interview.

Resend an invitation

POST/v1/invitations/{id}/resendScope invitations:write

A 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 fieldTypeDescription
expiresInDaysinteger1 to 60: the new link's days. Default: an expired invitation gets your company's link expiry; an open one keeps its deadline
curl -X POST https://api.testee.ai/v1/invitations/inv_mh3m8k1qz8x4pd/resend \  -H "Authorization: Bearer $TESTEE_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 8e0f6c1a-2b7d-4d0e-9a51-3c6f2e9b7d40" \  -d '{"expiresInDays":7}'
Response
{  "invitation": {    "id": "inv_mh3m8k1qz8x4pd",    "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",    "interviewId": "iv_mh3k2p9x4f7a2c",    "interviewTitle": "Backend engineer screen",    "status": "invited",    "expiresAt": "2026-11-19T10:02:44.000Z",    "createdAt": "2026-11-12T10:02:44.000Z",    "openedAt": null,    "startedAt": null,    "completedAt": null,    "sessionId": null,    "externalId": "req-2291",    "returnUrl": "https://careers.example.com/thanks",    "skipSignIn": false,    "opensAt": null,    "emailStatus": "sent",    "revokedAt": null  },  "link": "https://interview.testee.ai/i/Lm2r…"}
  • 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: 404 Invitation not found; 409 The candidate has already started this interview; 409 This interview was deleted, so the invitation can't be sent again; 429 (rate_limited, with Retry-After) after five resends of one invitation within an hour, from the dashboard and the API together.