Skip to main content

Quickstart

One assessment, end to end, in four calls.

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

1. Register the role

curl -X POST https://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://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://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://careers.example.com/launch/ehs_lt_9Qm2...",
  "assessment_id": "3b8e1d02-5c77-4c2a-8a41-9b2f7e6d4c10",
  "expires_at": 1767830400,
  "livemode": false
}

You get a single-use URL on your own branded domain if you have one configured. Email it, or put it behind a button in your product.

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://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, or a test assessment.
{
  "error": {
    "type": "not_found_error",
    "code": "report_not_ready",
    "message": "No report yet.",
    "request_id": "req_8f2c1d94ab6e4f0e",
    "doc_url": "https://docs.experthire.io/docs/hiring/errors#report_not_ready"
  }
}

A test assessment is never recorded, so it is never scored. Use a test key to build and verify the flow; use a live key when you need a real report.

Next