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
string
required
Your Hirebase API key. Required on every request — this is an always-authenticated, paid-feature endpoint.
Request Body
string
required
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.
string
Unique task ID (UUID). Use it to poll task status.
string
Always
"contacts_extraction" for this endpoint.string
Task state:
queued, processing, finished, or failed.number | null
Progress as a float between 0.0 and 1.0 (may be
null).string
ID of the user who initiated the task.
object
Echo of the request body, e.g.
{ "job_id": "..." }.string
ISO 8601 timestamp of task creation.
string
ISO 8601 timestamp of last update.
string | null
ISO 8601 timestamp when processing began, or
null.string | null
ISO 8601 timestamp when the task finished, or
null.string | null
Error message when
state is "failed", otherwise null.object | 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.