# Screening interview

> POST /screening-interview invites candidates to a hosted, recorded screening and sends each signed answer, with transcript and recording link, to your server.

**Source:** /docs/api/screening-interview/ (Curriculo Docs)  
**Updated:** 12 October 2026  
**Contact:** hello@curriculo.me

```http
POST https://api.curriculo.me/public/screening-interview
GET https://api.curriculo.me/public/screening-interview/{screening_id}
```

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.

> [!NOTE]
> 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". |

```bash
curl -X POST https://api.curriculo.me/public/screening-interview \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate_emails": ["ada@example.com"],
    "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](/docs/background-processing/#verify-the-signature).

```json
{
  "screening_id": "...",
  "email": "ada@example.com",
  "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.

> [!NOTE]
> 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

```bash
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](/docs/data-handling/).