Skip to main content

Quickstart

One assessment, end to end, in four calls.

Four calls. Use a sandbox key throughout; nothing here costs a credit.

1. Register the role

curl -X POST https://hiring-api.experthire.cloud/v1/jobs \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Backend Engineer","description":"Go, Postgres, distributed systems."}'

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

201Response
{
  "object": "job",
  "id": "9c1f0b7e-2f4a-4a51-9a2e-6f0d5b3c1a88",
  "title": "Backend Engineer",
  "description": "Go, Postgres, distributed systems.",
  "livemode": false,
  "created_at": 1767225600
}

Keep the id. You register a role once and reference it for every candidate.

2. Create the assessment

curl -X POST https://hiring-api.experthire.cloud/v1/assessments \
  -H "Authorization: Bearer $EH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "type": "ai_interview",
        "job_id": "$JOB_ID",
        "candidate": { "email": "[email protected]", "name": "Ada Lovelace" },
        "duration_minutes": 20
      }'

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

201Response
{
  "object": "assessment",
  "id": "3b8e1d02-5c77-4c2a-8a41-9b2f7e6d4c10",
  "type": "ai_interview",
  "status": "scheduled",
  "job_id": "9c1f0b7e-2f4a-4a51-9a2e-6f0d5b3c1a88",
  "candidate_id": "7e2a94c1-0f3b-4d88-b6a2-1c5e8f0a9d33",
  "livemode": false,
  "created_at": 1767225601,
  "updated_at": 1767225601
}

The candidate is created if we have not seen them before. duration_minutes sets how long the interviewer stays on the call, and how many questions it gets through; omit it to take the round type's default.

Send Idempotency-Key on every create. A retry then returns the original result instead of making a second assessment.

3. Send the candidate in

curl -X POST https://hiring-api.experthire.cloud/v1/assessments/$ASSESSMENT_ID/launch-link \
  -H "Authorization: Bearer $EH_SECRET_KEY"

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

201Response
{
  "object": "launch_link",
  "url": "https://room.experthire.io/launch?token=ehs_lt_9Qm2...&api=https%3A%2F%2Fhiring-api.experthire.cloud",
  "assessment_id": "3b8e1d02-5c77-4c2a-8a41-9b2f7e6d4c10",
  "expires_at": 1767830400,
  "livemode": false
}

You get a single-use URL pointing at the assessment room we host. Email it, or put it behind a button in your product. Treat it as opaque: the token and the originating API both travel in the query string, so rewriting the URL breaks it.

To embed the interview in your own page instead, allowlist your origin with POST /v1/domains, then mint a browser session with POST /v1/sessions. Never put your secret key in a browser.

4. Read the result

Register a webhook endpoint and wait for interview.completed rather than polling.

curl https://hiring-api.experthire.cloud/v1/assessments/$ASSESSMENT_ID/report \
  -H "Authorization: Bearer $EH_SECRET_KEY"

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

200Trimmed. See Reports for every field.
{
  "object": "assessment_report",
  "assessment_id": "3b8e1d02-5c77-4c2a-8a41-9b2f7e6d4c10",
  "status": "completed",
  "score": 68,
  "summary": "Answered clearly with concrete examples, hesitant on trade-offs.",
  "feedback": {
    "overall_score": 68,
    "field_knowledge": [
      { "criteria": "Ownership of recent work", "score": 74, "comments": "..." }
    ],
    "speech_analysis": [
      { "criteria": "Fluency", "rating": 72, "comments": "Steady pace." }
    ],
    "behavioural_analysis": [
      { "label": "Eye Contact", "score": 0, "outcome": "Not Analyzed (Audio Only)" }
    ]
  },
  "media": { "recording_url": "https://...", "transcript_url": "https://..." },
  "generated_at": 1767229200
}
404Not scored yet.
{
  "error": {
    "type": "not_found_error",
    "code": "report_not_ready",
    "message": "No report yet.",
    "request_id": "req_8f2c1d94ab6e4f0e",
    "doc_url": "https://docs.experthire.io/hiring/errors#report_not_ready"
  }
}

A sandbox assessment is never recorded, so nothing is measured. Its report returns 200 with fixed numbers and "sample": true. Build against it, but branch on sample and use a live key for a real result.

Next