Skip to content

API

Candidates.

The people you invite. One candidate per company and email address.

Last updated 19 November 2026

The candidate object

FieldTypeDescription
idstringUse it as candidateId when inviting
namestringFull name
emailstringWhere invitations are sent; unique within the company
headlinestring or nullWhat the person does, one line
externalIdstring or nullAn id from another system, when one was stored
createdAtdate-timeWhen the candidate was created

Create a candidate

POST/v1/candidatesScope candidates:write
Body fieldTypeDescription
namestring, required1 to 200 characters
emailstring, requiredA valid email address
headlinestringUp to 120 characters
externalIdstringYour own id for the person, such as their ATS id, up to 200 characters; find them by it with ?externalId=
curl -X POST https://api.testee.ai/v1/candidates \  -H "Authorization: Bearer $TESTEE_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 8e0f6c1a-2b7d-4d0e-9a51-3c6f2e9b7d40" \  -d '{"name":"Ada Lovelace","email":"ada@example.com","headline":"Senior software engineer"}'
Response
{  "id": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",  "name": "Ada Lovelace",  "email": "ada@example.com",  "externalId": null,  "headline": "Senior software engineer",  "createdAt": "2026-11-12T10:02:31.000Z"}

An email that already has a candidate in your company is a 409 with A candidate with this email already exists. Accepts Idempotency-Key (Idempotency).

List candidates

GET/v1/candidatesScope candidates:read

Newest first. Takes limit, cursor and externalId (only the candidates with that id from another system, an exact match). An invalid filter is a 400 with issues.

curl "https://api.testee.ai/v1/candidates?limit=50" \  -H "Authorization: Bearer $TESTEE_API_KEY"
Response
{  "data": [    {      "id": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",      "name": "Ada Lovelace",      "email": "ada@example.com",      "externalId": null,      "headline": "Senior software engineer",      "createdAt": "2026-11-12T10:02:31.000Z"    }  ],  "nextCursor": "eyJjIjoiMjAyNi0xMS0wMlQwOToxNDowNS4wMDBaIiwiaSI6Iml2XzEifQ"}

Get a candidate

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

One candidate of your company. 404 with Candidate not found. for an id outside your company and once the candidate's erasure was requested.

curl https://api.testee.ai/v1/candidates/cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f \  -H "Authorization: Bearer $TESTEE_API_KEY"
Response
{  "id": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",  "name": "Ada Lovelace",  "email": "ada@example.com",  "externalId": null,  "headline": "Senior software engineer",  "createdAt": "2026-11-12T10:02:31.000Z"}

Erase a candidate

DELETE/v1/candidates/{id}Scope candidates:delete

For a data-subject erasure request. Starts deleting the candidate and everything about them in every part of the product: invitations, sessions, transcripts, audio, analyses and reviewer notes. This can't be undone. Answers 202 with the erasure request; its status turns complete once every service confirmed.

curl -X DELETE https://api.testee.ai/v1/candidates/cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f \  -H "Authorization: Bearer $TESTEE_API_KEY"
202 Accepted
{  "id": "er_mh3q0b2k7d1xq4",  "candidateId": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",  "companyId": "co_acme",  "reason": "request",  "requestedBy": "api:key_8d2f",  "requestedAt": "2026-11-12T16:20:00.000Z",  "expected": [    "candidate",    "session",    "analysis",    "integration",    "notification",    "interview",    "assistant"  ],  "completed": {},  "status": "pending",  "completedAt": null}