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":"ada@example.com","name":"Ada Lovelace"}'

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

{
  "object": "candidate",
  "id": "8f14e45f-ceea-467a-9f7c-9a1d3e2b5c11",
  "email": "ada@example.com",
  "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, so it is scored from the transcript alone. Until that finishes, step 4 returns a sample report with "sample": true; wait for interview.summary_available to read the real one.

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