Pular para o conteúdo

API

API quickstart.

Invite a candidate to an AI interview from your own system and read the results, in four requests.

Última atualização: 19 de novembro de 2026

A documentação para desenvolvedores está disponível apenas em inglês.

How the API works

The REST API lets your systems (an ATS, a careers site, an internal tool) do what a recruiter does in the dashboard: list your published interviews, create candidates, invite them, follow their progress and fetch their results. Every request goes to https://api.testee.ai/v1 over HTTPS, with JSON in and out. That is the host of the EU data region, where every company is today; a company in another data region uses its region's host (api.us.testee.ai for the US), and a key only works on its own region's host: elsewhere it is a 401.

  • One company per key. An API key belongs to one company and only ever sees that company's data.
  • Results are for review. Scores are AI coverage of your own expectations, for your team to review, never a hiring decision.
  • A machine-readable spec. GET /v1/openapi.json returns the OpenAPI 3.1 document, and /v1/docs is a browsable reference built from it.

Before you start

  • The free trial or a paid plan: on the trial the API works within its interview minutes, with one webhook endpoint; the ATS and the embed come with a paid plan.
  • A company admin (or an organization owner or admin) to create the key.
  • At least one published interview: invitations always use an interview's published version.

1. Create an API key

  1. Open Integrations. In the dashboard, go to Integrations → API keys and press New key.
  2. Pick its permissions. For this guide: interviews:read, candidates:write, invitations:write and results:read.
  3. Copy the key. It starts with aik_live_ and is shown once. Keep it in your secret manager, never in client-side code.
Shell
export TESTEE_API_KEY=aik_live_…

2. Find the interview

List your published interviews and keep the id of the one to invite to.

curl https://api.testee.ai/v1/interviews \  -H "Authorization: Bearer $TESTEE_API_KEY"
Response
{  "data": [    {      "id": "iv_mh3k2p9x4f7a2c",      "title": "Backend engineer screen",      "roleTitle": "Backend engineer",      "seniority": "senior",      "durationMin": 30,      "blockCount": 4,      "createdAt": "2026-11-02T09:14:05.000Z"    }  ],  "nextCursor": null}

3. Create the candidate

A candidate is a person, once per company and email address. The Idempotency-Key makes a retry after a timeout safe.

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"}'
Response
{  "id": "cand_4f1b9c0e7a2d5e8f3b6c9a1d0e4f",  "name": "Ada Lovelace",  "email": "ada@example.com",  "externalId": null,  "headline": "Senior software engineer",  "createdAt": "2026-11-12T10:02:31.000Z"}

4. Invite them

The invitation is emailed to the candidate right away. The response also carries the link, shown only this once: send it yourself, or open it on your own site with the embed SDK.

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"}'
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": null,    "returnUrl": null,    "skipSignIn": false,    "opensAt": null,    "emailStatus": "sent",    "revokedAt": null  },  "link": "https://interview.testee.ai/i/x9Qf…"}

5. Get the results

When the candidate finishes and the analysis is done, a results.ready webhook names the session. Fetch its results with GET /v1/sessions/{id}/results. Without webhooks, poll the invitation until it has a sessionId, then the results until analysisStatus is done (when results.ready is sent; partial: true if some blocks couldn't be analyzed) or error (the analysis failed; your team can retry it from the results page, resultsUrl). Don't go by the blocks: they appear one by one as the analysis runs, so an empty or half-filled blocks list can look finished.

Getting help

Every API response carries an X-Request-Id header. When something goes wrong, write to hello@testee.ai with that id, the time and the route: it finds the request in our logs. On Enterprise plans, availability and support response times are in the SLA.