Hiring Manager Contacts API
Hiring Manager API
Hiring Manager Contacts API
Extract likely hiring-manager / recruiter contacts for a specific job posting.
POST
Hiring Manager Contacts API
Beta. The Contacts API is in private beta. To request access, email
spencer@hirebase.org.
job_id, then poll the
Task Status endpoint until the
extraction finishes.
Endpoint
Authentication
Your Hirebase API key. Required on every request — this is an always-authenticated, paid-feature endpoint.
Request Body
The job’s MongoDB ObjectId (
_id from any
Search Jobs result).Response
Returns a task object immediately (the extraction runs asynchronously). Use the returnedid to poll GET /v2/tasks/{task_id}.
When state becomes "finished", result.contacts is populated.
Unique task ID (UUID). Use it to poll task status.
Always
"contacts_extraction" for this endpoint.Task state:
queued, processing, finished, or failed.Progress as a float between 0.0 and 1.0 (may be
null).ID of the user who initiated the task.
Echo of the request body, e.g.
{ "job_id": "..." }.ISO 8601 timestamp of task creation.
ISO 8601 timestamp of last update.
ISO 8601 timestamp when processing began, or
null.ISO 8601 timestamp when the task finished, or
null.Error message when
state is "failed", otherwise null.Present only when
state is "finished".Example
1. Start the extraction
Response — task created
2. Poll for the result
Response — finished
Timing: in testing this extraction took ~4–5 minutes end-to-end. Build for minute-scale latency, not seconds. Coverage:
email and photo_url are often null — name, role, and profile_url (LinkedIn) are the most reliably populated fields.Error Responses
403 Forbidden
403 Forbidden
Your account doesn’t have Contacts API access. This feature is in beta — email spencer@hirebase.org for access.
422 Unprocessable Entity
422 Unprocessable Entity
Missing or malformed
job_id. Body: { "detail": [ { "type": "missing", "loc": ["body","job_id"], "msg": "Field required", "input": {} } ] }.Task failed (state: "failed")
Task failed (state: "failed")
A job that can’t be resolved or for which no contacts could be found will create a task that completes with
state: "failed" and a populated error field (rather than failing the initial request). Always check the task state after polling.Notes & Best Practices
- Poll, don’t block. Extraction typically takes seconds to a few minutes. Poll
GET /v2/tasks/{id}every few seconds; treatfinishedandfailedas terminal. - Contacts are best-effort.
profile_url,email, andphoto_urlmay benullwhen not found;contactsmay be empty for some postings. - The task object is the same shape used by Export Jobs — only
type(contacts_extraction) andresultdiffer.