API reference

Getting started

1. Mint an API key

Sign in to the SmartHire dashboard, open Settings → API keys, and click Create key. Give each integration its own key so you can revoke one without breaking the others.

2. Send the key on every request

Every request carries the raw key in the X-API-Key header. Keys start with the literal prefix sk_smarthire_ so accidental leaks are grep-able in logs and git history.

curl -H "X-API-Key: $SMARTHIRE_API_KEY" \
  https://api.smarthire.chat/v1/jobs

3. Scopes

A newly-minted key carries the three read scopes needed for the endpoints below. A request with a valid key but the wrong scope returns 403 api_key_no_scopes.

• read:jobs — list and fetch jobs.
• read:applications — list and fetch applications.
• read:interviews — list and fetch interviews.

4. Rate limits

Per-key token bucket: 10 requests per second sustained, burst of 20. When you exceed the cap the API returns 429 rate_limited with a Retry-After header (whole seconds). A well-behaved client honours the header instead of retrying immediately.

5. Pagination

List endpoints return { "data": [...], "next_cursor": "..." | null }. When next_cursor is non-null, pass it back verbatim as ?cursor= to fetch the next page. Cursors are opaque; do not try to decode or synthesise them.

GET /v1/jobs?limit=50
→ { "data": [...], "next_cursor": "eyJvZmZzZXQiOjUwfQ" }

GET /v1/jobs?limit=50&cursor=eyJvZmZzZXQiOjUwfQ
→ { "data": [...], "next_cursor": null }

Default limit is 25, maximum is 100. Values outside that range return 422.

6. Errors

Every error is a JSON document of shape {"detail": {"error_code": "...", "message": "..."}}. Switch on error_code; the message field is human-readable and may change. Common codes: api_key_missing, api_key_malformed, api_key_invalid, api_key_revoked, api_key_no_scopes, rate_limited, invalid_cursor, job_not_found, application_not_found, interview_not_found.

Examples

List jobs

curl -H "X-API-Key: $SMARTHIRE_API_KEY" \
  "https://api.smarthire.chat/v1/jobs?limit=25"

List applications for one job

curl -H "X-API-Key: $SMARTHIRE_API_KEY" \
  "https://api.smarthire.chat/v1/applications?job_id=<JOB_ID>&status=pending_review"

List scheduled interviews

curl -H "X-API-Key: $SMARTHIRE_API_KEY" \
  "https://api.smarthire.chat/v1/interviews?status=scheduled"

PII policy

The /v1 surface never returns:

• Candidate name, phone number, or hashed phone number as a bare field.
• CV file content, filename, or storage key.
• Screening answers, transcripts, or WhatsApp message bodies.
• Interviewer email or phone (only the display name).
• Location coordinates or postal addresses (only the human-readable name).

Application identifiers embed a hashed phone by construction (<job_id>_<phone_hash>) so the same candidate can be joined across your ATS, but the hash itself does not re-identify anyone.

Full reference

The full schema below is generated from the live server and describes every request parameter, response field, and error shape. Try any call directly from the browser using your API key.