IQ Metrics for Business · For developers
Add pre-employment assessments to your own applicant tracking system, HR platform, careers site or website: create assessments, invite candidates and receive their results. REST and JSON, sandbox keys from your first sign-in, and a signed webhook the moment a result is ready.
https://iqmetrics.org/api/v11.0.0-draft.2JSON · OpenAPI 3.134Read the documentationGet sandbox keys
# Invite a candidate from your ATS
API=https://iqmetrics.org/api/v1
curl -X POST "$API/assessments/asm_7Q2m…/invitations" \
-H "Authorization: Bearer $IQM_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"candidate": {"email": "sam@example.com",
"external_id": "ats-9921"}}'// Invite a candidate from your ATS
await fetch(`${API}/assessments/${id}/invitations`, {
method: "POST",
headers: { Authorization: `Bearer ${IQM_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({ candidate: { email, external_id } }),
});# Invite a candidate from your ATS
requests.post(
f"{API}/assessments/{assessment_id}/invitations",
headers={"Authorization": f"Bearer {IQM_KEY}",
"Idempotency-Key": str(uuid.uuid4())},
json={"candidate": {"email": email,
"external_id": ats_id}},
){
"id": "inv_8KD2wT4y…",
"status": "invited",
"candidate_url": "https://iqmetrics.org/assess/c/9f1b…",
"expires_at": "2026-10-11T09:31:00Z"
}Everything the company dashboard does, the API does too. A typical integration is three requests and one webhook, and it runs against the sandbox until you switch the key.
/assessmentsFrom a ready-made test, a role template, or your own sections: the categories, the questions in each, the difficulty and the time limit. The reply carries the builder’s warnings.
{ "name": "Operations Analyst",
"test": "general-aptitude",
"settings": { "expires_in_days": 7,
"redirect_url": "https://…/thanks" } }/assessments/{id}/invitationsOne candidate, or up to 500 in a batch. We email the link in the company’s brand, or you deliver it yourself from the reply. Keep your own IDs on it with external_id and metadata.
{ "candidate": { "email": "sam@example.com",
"external_id": "ats-9921" },
"send_email": false,
"metadata": { "requisition": "OPS-114" } }result.readyA signed webhook with IDs only, retried until your endpoint answers. No polling, and never a score or a personal detail in transit.
{ "type": "result.ready",
"data": { "invitation_id": "inv_8KD2wT4y…",
"result_id": "res_5Rt7Yu9I…" } }/invitations/{id}/resultScore, categories, band, rank, percentile, time used and integrity signals, plus a signed link to the PDF report that is valid for an hour.
{ "score": { "correct": 17, "total": 24 },
"band": "above_typical",
"rank": { "position": 3, "of": 41 },
"signals": { "tab_switches": 1, "paste_attempts": 0 } }Two kinds of teams use it: hiring companies and HR software that connect their own systems, and websites that show our tests to their visitors. Candidates invited through the API appear in the company dashboard too, so recruiters and your integration see the same assessments, candidates and results.
Create the assessment when a requisition opens, invite each applicant as they reach the screening stage, and write the result back to the candidate’s record when result.ready arrives. Find invitations again by your own external_id.
Invite with send_email off and show the candidate their personal link yourself, then set redirect_url so they land back on your site when they finish. The test runs on our page, with its clock and scoring on our server.
Send up to 500 invitations in one batch and read the batch’s outcome line by line. List results by assessment, download the PDF for each, and read a campus drive’s seats by their drive_id.
Show shared tests to your visitors: embed our test page with a public key, or fetch one question at a time through the question API and draw it in your own design. A separate pool, never the hiring questions.
How shared tests workGenerated from the OpenAPI file this page is built against, so the list below is the API as it is. Each line opens its entry in the documentation, with a checked example request and reply.
/assessments/{assessment_id}/invitationsList an assessment’s invitations/assessments/{assessment_id}/invitationsInvite a candidate/assessments/{assessment_id}/invitations/bulkInvite up to 500 candidates at once/invitation-batches/{batch_id}Get a batch of invitations/invitations/{invitation_id}Get an invitation/invitations/{invitation_id}/resendRe-issue the candidate’s link/invitations/{invitation_id}/cancelCancel an invitation/invitations/{invitation_id}/extendMove the invitation’s deadline, or give extra time/webhooksList webhook endpoints/webhooksAdd a webhook endpoint/webhooks/{webhook_id}Get a webhook endpoint/webhooks/{webhook_id}Change a webhook endpoint/webhooks/{webhook_id}Remove a webhook endpoint/webhooks/{webhook_id}/rotate-secretReplace the signing secret/webhooks/{webhook_id}/testSend a test event/webhooks/{webhook_id}/deliveriesList an endpoint’s deliveries/webhooks/{webhook_id}/deliveries/{delivery_id}/replaySend a delivery againAdmins and developers sign in with their work account and manage keys, webhooks and logs in the dashboard. You never need to ask us for a key.
iqm_live_9c1d…Used 2 min agoRevokeiqm_live_4f2a…Used todayRevokeA get-started checklist, today’s calls, the error rate and response time, and an example request to copy.
Create and revoke keys yourself. Choose what each key may do and when it expires. A key is shown once; we keep only its fingerprint.
Add endpoints, choose their events, send a test event, replay a delivery and rotate the signing secret. A failing endpoint is paused, not forgotten.
Usage for the current month, and the last 30 days of API calls: time, request, status, key, duration and request ID. Never bodies, query strings or personal data.
The shared tests your website may show, with display settings: your brand or ours, and how a result is shown.
The websites the embed may run on, which you add and remove yourself, and your public keys.
Add an HTTPS endpoint, pick its events, and we tell you the moment something happens. Every delivery is signed in the Standard Webhooks format and carries IDs only.
webhook-id, so a receiver that already has the event can ignore it.8 events an endpoint can receive
result.readyA result is readyinvitation.openedA candidate opened their linksession.startedA candidate started the testinvitation.expiredAn invitation expired unusedinvitation.bouncedThe invitation email bouncedusage.threshold_reachedA usage counter reached 80% or 100% of its limitshared_session.completedA shared session is overwebhook.testA test event, sent from the developer dashboard or the APIPOST https://ats.example.com/hooks/iqm
webhook-id: evt_6Yh4Tg2R…
webhook-timestamp: 1791036900
webhook-signature: v1,K5oZfzN95Z9UVu1Esf…
{
"type": "result.ready",
"data": {
"invitation_id": "inv_8KD2wT4y…",
"result_id": "res_5Rt7Yu9I…"
}
}The conventions you would expect from a payments API, applied to hiring: repeat-safe writes, one error shape, limits you can read, and a version that never breaks what you built.
Every create takes an Idempotency-Key. Send a timed-out request again and you get the first reply, with nothing created twice. Keys are remembered for 24 hours.
RFC 9457 Problem Details on every error, with a stable code to act on, a request_id to quote to us, and the failing field named on validation errors.
RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every reply, and Retry-After when you are over.
New fields and endpoints, never a removal. A breaking change would come as a new version, announced with Deprecation and Sunset headers.
A request with a field the API does not know is refused, so a typo never passes silently. Replies may gain fields; ignore the ones you don’t know.
Lists come one page at a time, 1 to 100 items, with a next_cursor to pass back. Filter results by assessment and date, and invitations by status or your own external_id.
Every ID says what it is: asm_, inv_, res_, whk_. Every object carries livemode, so sandbox and live data can never mix.
An external_id on every candidate and up to 20 metadata values on every invitation, returned unchanged.
Keys that start with iqm_test_ work on sandbox data: a sample test with 20 questions, sample shared tests, and no email that ever reaches a real candidate. Invite yourself, take the test, and read the result, all from your terminal.
curl https://iqmetrics.org/api/v1/usage \
-H "Authorization: Bearer $IQM_KEY"
# 200 with "livemode": false means the key works on the sandboxThe API serves company accounts that hold candidates’ personal data, so every key, every delivery and every log is designed to give away as little as possible.
A key appears once, when it is made, and we keep only its fingerprint. Each key carries only the scopes it needs, from 11 available, and expires when you say.
Keys are for your servers. The API sends no CORS headers, so a key that leaks into a web page cannot be used from a browser.
Every record carries its company, and another company’s objects answer not found, never forbidden, so nothing can be enumerated.
A webhook never holds a score or a personal detail. Your endpoint must be HTTPS on the public internet, and our deliveries are pinned to the address they resolved.
The request log keeps the time, path, status, key, duration and request ID. Never a body, a query string or a candidate’s details.
One call deletes a candidate and everything linked to them. Report links are signed and expire within an hour. Every deletion is in the audit log.
Job boards, career sites, universities, publishers and coaches can add our reasoning tests to their own website for their visitors. These come from a separate pool we set aside for sharing, never from the questions we keep for hiring.
Choose
Pick the shared tests your website shows in the developer dashboard, and choose your own brand or ours, and whether visitors see a score or a score with a percentile.
Inside your page
One script with a public key runs the test inside your page, only on the websites you list yourself. The clock and the scoring stay on our server, and a copied code cannot run anywhere else.
Your own design
Your server starts a session, fetches one unit at a time without its answer key, shows it in your own design and sends the answers back. We score them and send shared_session.completed.
A hiring assessment API lets your own software run pre-employment tests without anyone opening our dashboard: it creates an assessment, invites a candidate and receives the scored result. Ours is a REST API with JSON, scoped keys and signed webhooks, and everything it creates also appears in the company dashboard.
Two groups. Hiring companies and HR software, such as an applicant tracking system, an HR platform or a campus recruiting tool, use it to invite candidates and read their results. Websites, such as job boards, career sites, schools and publishers, use the embed or the question API to show our shared tests to their own visitors.
Create the assessment once, then invite each applicant with POST /assessments/{id}/invitations when they reach the screening stage, keeping your own candidate ID in external_id. Add a webhook endpoint for result.ready, and read the result into the candidate’s record when it arrives. The quick start walks through it in the sandbox.
Yes, with shared tests. Paste the embed script with a public key on the websites you list, or draw the questions in your own design with the question API. Shared tests come from a separate pool, never the hiring questions, and the answer key stays on our server.
Assessments, invitations, batches, results, the PDF report, candidate deletion, webhooks and usage: yes. The hiring stages and team notes a recruiter keeps are for the dashboard only and never appear in the API.
Create your company account with a work email, sign in, open the developer dashboard and create a sandbox key. It starts with iqm_test_ and is shown once. Live keys become available once our team has checked your company, and creating one asks for the code from your authenticator app.
Not yet. The API is plain REST and JSON described in an OpenAPI 3.1 file, which most code generators read directly. The documentation shows every request as cURL, and the webhook check in Node.js, Python and PHP.
Yes. Add an endpoint in the sandbox, send it a test event from the dashboard or the API, and watch every attempt in the delivery log. Sandbox and live endpoints are separate.
Limits are set for each key, and every reply tells you where you stand in its RateLimit headers. Over the limit you get a 429 with Retry-After. An address that keeps sending requests with a bad key is refused for up to 10 minutes.
No. Version 1 only ever gains fields and endpoints. Anything that would break an existing integration would ship as a new version, with the old one kept and announced ahead with Deprecation and Sunset headers.
For hiring, candidates take the test on our page, from the personal link, and redirect_url brings them back to you. For shared tests on your website, the embed runs our test page inside yours, and the question API lets you draw the questions yourself.
In the X-Request-Id header of every reply, in the request_id field of every error, and in the request log of the developer dashboard. Quote it when you write to us.
Create your company account with your work email. The sandbox is ready as soon as you sign in: create a sandbox key in the developer dashboard and start building.
Already have an account? Sign in. Hiring without code? See the company dashboard. Putting tests on your website? See how shared tests work.