Skip to main content

Quickstart

Run a complete interview end to end, from key to scored report.

This runs a real interview in sandbox. Nothing here spends live credits, and sandbox never emails your candidate.

You need a sandbox secret key, which starts ehp_sk_test_.

Secret keys are server-side only. A key in browser JavaScript can create interviews, read every report in your organisation, and spend your credits.

1. Create a candidate

curl -X POST https://prep-api.experthire.cloud/v1/candidates \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Ada Lovelace"}'

Still a placeholder: $EH_SECRET_KEY. Add it under Your values above.

{
  "object": "candidate",
  "id": "8f14e45f-ceea-467a-9f7c-9a1d3e2b5c11",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "created_at": 1770000000
}

Candidates never sign in. You own the relationship; we only need somewhere to attach the results.

2. Create an interview

curl -X POST https://prep-api.experthire.cloud/v1/interviews \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "8f14e45f-ceea-467a-9f7c-9a1d3e2b5c11",
    "round_type": "general_interview",
    "difficulty": 3,
    "role": "Backend Engineer"
  }'

Still a placeholder: $EH_SECRET_KEY. Add it under Your values above.

{
  "object": "interview",
  "id": "1c9d6b3a-77aa-4e21-8b0e-6b2f9c4d1a55",
  "status": "Scheduled",
  "candidate_id": "8f14e45f-ceea-467a-9f7c-9a1d3e2b5c11",
  "round_type": "general_interview",
  "difficulty": 3,
  "role": "Backend Engineer",
  "report_available": false,
  "environment": "sandbox",
  "livemode": false
}

This reserves five credits from your organisation's credit pool. Cancelling before the candidate joins returns them.

3. Get the candidate a link

curl -X POST https://prep-api.experthire.cloud/v1/interviews/$INTERVIEW_ID/launch-link \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 604800}'

Still a placeholder: $INTERVIEW_ID, $EH_SECRET_KEY. Add them under Your values above.

{
  "object": "launch_link",
  "interview_id": "1c9d6b3a-77aa-4e21-8b0e-6b2f9c4d1a55",
  "url": "https://room.sandbox.experthire.io/launch?token=ehp_lt_...",
  "expires_at": 1770604800
}

Send that URL to the candidate. It is single use, and the token is stored hashed, so this response is the only time you will see it. Losing it means minting another.

Open the link yourself and complete a short interview. In sandbox the interview is capped at five minutes and is not recorded, and because scoring runs off that recording it is never scored. Step 4 still works: sandbox returns a sample report with "sample": true so you can build the parser. Use a live key for real scores.

4. Read the report

You will get an interview.completed webhook when scoring finishes. To fetch it directly:

curl https://prep-api.experthire.cloud/v1/interviews/$INTERVIEW_ID/report \
  -H "Authorization: Bearer $EH_SECRET_KEY"

Still a placeholder: $INTERVIEW_ID, $EH_SECRET_KEY. Add them under Your values above.

{
  "object": "interview_report",
  "interview_id": "1c9d6b3a-77aa-4e21-8b0e-6b2f9c4d1a55",
  "status": "Completed",
  "overall_score": 72,
  "summary": "Ada reasoned clearly about trade-offs...",
  "media": {
    "transcript_url": "https://...",
    "has_whiteboard": false
  },
  "events": [],
  "duration_seconds": 284,
  "generated_at": 1770000600
}

Media URLs are signed and expire in two hours. Fetch them when you need them rather than storing them.

Next