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.jsonreturns the OpenAPI 3.1 document, and/v1/docsis 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
- Open Integrations. In the dashboard, go to Integrations → API keys and press New key.
- Pick its permissions. For this guide:
interviews:read,candidates:write,invitations:writeandresults:read. - Copy the key. It starts with
aik_live_and is shown once. Keep it in your secret manager, never in client-side code.
2. Find the interview
List your published interviews and keep the id of the one to invite to.
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.
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.
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.