مواد پر جائیں

API

API quickstart.

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

آخری اپ ڈیٹ 19 نومبر، 2026

ڈویلپر دستاویزات صرف انگریزی میں دستیاب ہیں۔

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.