Skip to main content

Quickstart

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

Expert Hire developer workflow for Quickstart
Build against the same evidence trail the product uses.

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 one interview credit. Cancelling before the candidate joins returns it.

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.

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