Screening interview

POSThttps://api.curriculo.me/public/screening-interview

GEThttps://api.curriculo.me/public/screening-interview/{screening_id}

On this page

Request
Response
Callbacks
Get a screening
Data handling

Send candidate email addresses, questions, job metadata and a callback URL. Curriculo emails each candidate a link to the interview, hosts the recording, transcribes each answer, and POSTs each answer to your callback_url as it comes in. A failed address does not cancel the others.

Price: $0.02 per invite actually sent. Failed invites are not charged.

These endpoints are not yet in the OpenAPI specification or Swagger UI. Call them directly with your Console key.

Request

application/json

Field	Required	Notes
`candidate_emails`	Yes	1 to 50 plain email addresses.
`questions`	Yes	1 to 10 questions. The candidate answers them in order.
`callback_url`	Yes	`https` URL on your server. We POST each answer here. No user name, password or `#` fragment in the URL.
`job_title`	No	Shown in the invite. Defaults to "Screening".
`company`	No	Shown in the invite. Defaults to "the hiring team".

curl -X POST https://api.curriculo.me/public/screening-interview \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate_emails": ["[email protected]"],
    "questions": ["Tell us about a system you shipped."],
    "callback_url": "https://example.com/screening",
    "job_title": "Backend engineer"
  }'

Response

The call answers 202 with a screening_id, a callback_secret shown once, sent_count, and an invites list. Each invite is sent or failed. Store the callback_secret.

Callbacks

Each answer is one signed POST to your server. X-Curriculo-Signature is sha256= plus the lowercase hex HMAC-SHA256 of the raw body, keyed with the callback_secret from the 202 (used as-is). Verify it exactly as for background task callbacks.

{
  "screening_id": "...",
  "email": "[email protected]",
  "question": "Tell us about a system you shipped.",
  "question_index": 0,
  "transcript": "I shipped the billing service.",
  "recording_url": "https://api.curriculo.me/public/screening-interview/.../recording",
  "media_kind": "video",
  "duration_seconds": 142,
  "completed": false
}

question_index starts at 0.
completed stays false until that candidate has a final answer for every question.
The recording_url is a private Curriculo media link, meant for your ATS result page, where recruiters can watch the answer beside the transcript.

The callback URL is your backend URL, not a candidate page and not a recruiter dashboard. Curriculo sends signed, machine-readable results there; your product decides how recruiters see them.

Get a screening

curl https://api.curriculo.me/public/screening-interview/<screening_id> \
  -H 'Authorization: Bearer key_abc123_yoursecret'

Read a screening's results at any time. If an old recording link has expired, request the screening again to receive a fresh media URL.

Data handling

Screening interviews keep invites, candidate answers and recordings so your ATS can retrieve completed recordings and transcripts. See Data handling.

Updated 12 October 2026