Assessments
Creating, shaping and reading an assessment.
An assessment is one candidate against one role. It is either a resume_screen
or an ai_interview, and both are the same resource to you.
Shaping the interview
Three things are yours to set, and none of them needs a round configured up front.
Length. duration_minutes, 5 to 120. This is a real lever, not a label: it
decides how long the interviewer stays on and how many questions it gets through.
Omit it and the round type's own default applies.
Shape. round_type picks the kind of conversation, for example
general_interview, hr_round or system_design. GET /v1/round-types lists
what your organisation can use and each one's default length.
Questions. questions is asked in place of generated ones. The first becomes
the opening question and the rest form the pool the interviewer draws from.
The interviewer samples that pool by length rather than asking every entry: roughly two questions on a 16-30 minute assessment, three up to 65, four otherwise. A list of ten on a fifteen-minute call is ten candidates for four slots, not a script.
Omit questions and we generate them from the role.
Repeat creates are cheap
Behind the scenes each distinct configuration gets one interview round, reused for every candidate you send with the same settings. Changing the length, the shape or the questions makes a new one. You never see this, and you never pay for question generation twice for the same setup.
Resume screens are not interviews
A resume_screen has no call, no length and no questions. It scores the
candidate's resume against the role. It comes back as the same assessment
resource with the same statuses, so one code path handles both.
Status
A list response wraps the rows and carries an opaque cursor.
{
"object": "list",
"data": [
{
"object": "assessment",
"id": "3b8e1d02-5c77-4c2a-8a41-9b2f7e6d4c10",
"type": "ai_interview",
"status": "completed",
"job_id": "9c1f0b7e-2f4a-4a51-9a2e-6f0d5b3c1a88",
"candidate_id": "7e2a94c1-0f3b-4d88-b6a2-1c5e8f0a9d33",
"score": 68,
"livemode": true,
"created_at": 1767225601,
"updated_at": 1767229200
}
],
"has_more": true,
"next_cursor": "c_b2ZmXzIw",
"total_count": 143
}
| Status | Meaning |
|---|---|
pending | Created, not yet scheduled |
scheduled | Ready for the candidate |
in_progress | Under way |
processing | Finished, being scored |
completed | Scored. The report is available |
cancelled | Ended without a result |
shortlisted and rejected also appear. Those are recruiter decisions made in
the dashboard, not something the assessment does to itself.
Test assessments
A test assessment behaves like a live one right up to scoring. It is never
recorded, so it never reaches completed and never produces a report. It also
never appears in your recruiters' pipeline and never spends a credit.
Build and verify against test. Use live when you need the result.
Next
- Scheduling — set when the candidate is expected
- Reports — read the scored result