Skip to main content
POST
Hiring Manager Contacts API
Beta. The Contacts API is in private beta. To request access, email spencer@hirebase.org.
Find the people likely behind a specific job posting — name, role, and (when available) LinkedIn profile, email, and photo. Submit a job_id, then poll the Task Status endpoint until the extraction finishes.
This is an asynchronous, agent-powered endpoint. Extraction runs web research in the background and can take anywhere from a few seconds to several minutes. Poll the task rather than blocking on a single request.

Endpoint

Authentication

x-api-key
string
required
Your Hirebase API key. Required on every request — this is an always-authenticated, paid-feature endpoint.

Request Body

job_id
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 returned id to poll GET /v2/tasks/{task_id}. When state becomes "finished", result.contacts is populated.
id
string
Unique task ID (UUID). Use it to poll task status.
type
string
Always "contacts_extraction" for this endpoint.
state
string
Task state: queued, processing, finished, or failed.
progress
number | null
Progress as a float between 0.0 and 1.0 (may be null).
user_id
string
ID of the user who initiated the task.
input
object
Echo of the request body, e.g. { "job_id": "..." }.
created_at
string
ISO 8601 timestamp of task creation.
updated_at
string
ISO 8601 timestamp of last update.
started_at
string | null
ISO 8601 timestamp when processing began, or null.
completed_at
string | null
ISO 8601 timestamp when the task finished, or null.
error
string | null
Error message when state is "failed", otherwise null.
result
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 nullname, role, and profile_url (LinkedIn) are the most reliably populated fields.

Error Responses

Missing or invalid API key. Body: { "detail": "Sign in to access this endpoint" } (missing key) or { "detail": "Invalid API key" }.
Your account doesn’t have Contacts API access. This feature is in beta — email spencer@hirebase.org for access.
Missing or malformed job_id. Body: { "detail": [ { "type": "missing", "loc": ["body","job_id"], "msg": "Field required", "input": {} } ] }.
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; treat finished and failed as terminal.
  • Contacts are best-effort. profile_url, email, and photo_url may be null when not found; contacts may be empty for some postings.
  • The task object is the same shape used by Export Jobs — only type (contacts_extraction) and result differ.