Hiring Manager Contacts API

curl --request POST \
  --url https://api.hirebase.org/v2/jobs/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "job_id": "<string>",
  "functions": [
    "<string>"
  ],
  "relationships": [
    "<string>"
  ],
  "exclude": {},
  "reveal_email": true,
  "reveal_phone": true
}
'

import requests

url = "https://api.hirebase.org/v2/jobs/contacts"

payload = {
    "job_id": "<string>",
    "functions": ["<string>"],
    "relationships": ["<string>"],
    "exclude": {},
    "reveal_email": True,
    "reveal_phone": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    job_id: '<string>',
    functions: ['<string>'],
    relationships: ['<string>'],
    exclude: {},
    reveal_email: true,
    reveal_phone: true
  })
};

fetch('https://api.hirebase.org/v2/jobs/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hirebase.org/v2/jobs/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'job_id' => '<string>',
    'functions' => [
        '<string>'
    ],
    'relationships' => [
        '<string>'
    ],
    'exclude' => [
        
    ],
    'reveal_email' => true,
    'reveal_phone' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hirebase.org/v2/jobs/contacts"

	payload := strings.NewReader("{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hirebase.org/v2/jobs/contacts")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hirebase.org/v2/jobs/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "<string>",
  "state": "<string>",
  "progress": {},
  "user_id": "<string>",
  "input": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": {},
  "completed_at": {},
  "error": {},
  "error_code": {},
  "retryable": {},
  "result": {
    "contacts": [
      {
        "name": "<string>",
        "role": "<string>",
        "profile_url": {},
        "email": {},
        "email_status": {},
        "phone_number": {},
        "phone_numbers": {},
        "photo_url": {},
        "function": "<string>",
        "relationship": "<string>"
      }
    ],
    "filtered": {},
    "reveals": {}
  }
}

POST

jobs

contacts

Hiring Manager Contacts API

curl --request POST \
  --url https://api.hirebase.org/v2/jobs/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "job_id": "<string>",
  "functions": [
    "<string>"
  ],
  "relationships": [
    "<string>"
  ],
  "exclude": {},
  "reveal_email": true,
  "reveal_phone": true
}
'

import requests

url = "https://api.hirebase.org/v2/jobs/contacts"

payload = {
    "job_id": "<string>",
    "functions": ["<string>"],
    "relationships": ["<string>"],
    "exclude": {},
    "reveal_email": True,
    "reveal_phone": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    job_id: '<string>',
    functions: ['<string>'],
    relationships: ['<string>'],
    exclude: {},
    reveal_email: true,
    reveal_phone: true
  })
};

fetch('https://api.hirebase.org/v2/jobs/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hirebase.org/v2/jobs/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'job_id' => '<string>',
    'functions' => [
        '<string>'
    ],
    'relationships' => [
        '<string>'
    ],
    'exclude' => [
        
    ],
    'reveal_email' => true,
    'reveal_phone' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hirebase.org/v2/jobs/contacts"

	payload := strings.NewReader("{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hirebase.org/v2/jobs/contacts")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hirebase.org/v2/jobs/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"job_id\": \"<string>\",\n  \"functions\": [\n    \"<string>\"\n  ],\n  \"relationships\": [\n    \"<string>\"\n  ],\n  \"exclude\": {},\n  \"reveal_email\": true,\n  \"reveal_phone\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "<string>",
  "state": "<string>",
  "progress": {},
  "user_id": "<string>",
  "input": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": {},
  "completed_at": {},
  "error": {},
  "error_code": {},
  "retryable": {},
  "result": {
    "contacts": [
      {
        "name": "<string>",
        "role": "<string>",
        "profile_url": {},
        "email": {},
        "email_status": {},
        "phone_number": {},
        "phone_numbers": {},
        "photo_url": {},
        "function": "<string>",
        "relationship": "<string>"
      }
    ],
    "filtered": {},
    "reveals": {}
  }
}

Requires the Hiring Manager API add-on. It is pay as you go with no monthly fee and works with any plan, including Free. Add it in the web app under Settings → Subscriptions. Keys without it receive 403 with X-Billing-Code: feature_missing.

Pricing. Settled when the task finishes, from what was actually found:

What	Price	Meter
Search that returns at least one contact	$0.30	`m_hiring_manager_runs`
Work email found (`reveal_email`)	$0.05 each	`m_contact_email_reveals`
Phone number found (`reveal_phone`)	$0.40 each	`m_contact_phone_reveals`

A search that finds no one, or fails, costs nothing; so does one where your functions / relationships filters and exclude list leave no one, and so does a reveal that finds nothing. Submitting the same job_id again within 24 hours of a charged search is not charged again (reveals you ask for on that call still are). Usage is charged when your unbilled usage reaches the current threshold or at the end of your billing month, whichever comes first. The threshold starts at $10 and rises to $50, then $100, after each successful charge. Web-app (dashboard) usage is not metered. See Usage Headers & Metering.

Find the people likely behind a specific job posting: name, role, and LinkedIn profile, plus a work email or phone number when you ask for them with reveal_email / reveal_phone. Each contact says how they relate to the role (relationship), and contacts come ranked: the hiring manager first, then the function’s leaders, then recruiters and HR. Submit a job_id, then poll the Task Status endpoint until the extraction finishes. To queue many postings at once, use Batch Submit (up to 100 per request) and poll them together with List Tasks.

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

POST /v2/jobs/contacts

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). Postings that have since expired are accepted: one that expired in the last 30 days is researched like a live one, and an older one returns contacts only if they were researched before (otherwise the task fails with job_expired). An id that matches no posting at all is rejected with 404 before any task is created.

string[]

Only return people in these functions: legal, hr, recruiting, executive, other. Each contact’s function is classified from its role title and returned as function. For example, ["legal", "hr", "recruiting"] drops COOs, claims managers and other roles outside those three. If nobody is left, the task fails with no_matching_contacts and is not charged.

string[]

Only return people with these relationships to the role: hiring_manager, function_leader, recruiter, hr, executive, other (see the relationship field below). For example, ["hiring_manager", "function_leader"] returns only the person the role reports to and the leaders of its team, without recruiters or HR. Combines with functions: a contact must match both. If nobody is left, the task fails with no_matching_contacts and is not charged.

object

People you already have, so they are not returned and never cost a reveal. Up to 10,000 entries in total. Excluded people are dropped before any email or phone lookup; if an email revealed for someone is on your list, they are dropped too and that reveal is not charged.

Show properties

string[]

LinkedIn profile URLs. Any form matches: www. or a country subdomain (uk.linkedin.com), with or without https://, a query string or a trailing slash, in any letter case.

string[]

Email addresses, case-insensitive.

boolean

default:"false"

Also look up a work email for every contact found. $0.05 per email actually found (`m_contact_email_reveals`), on top of the $0.30 search.

boolean

default:"false"

Also look up a direct phone number (mobile preferred) for every contact found. $0.40 per number actually found (m_contact_phone_reveals). Adds a minute or two to the task. Personal emails and numbers are never returned.

To reveal details for a single contact you already have, use Reveal Contact instead.

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.

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.

string | null

Machine-readable reason when state is "failed", otherwise null. See Why a task failed.

boolean | null

When state is "failed": true if submitting the same job_id again can succeed, false if it won’t. null otherwise.

object | null

Present only when state is "finished".

Show result properties

object[]

Array of contact objects. May be empty when no contacts could be found.

Show Contact properties

string

Full name of the contact.

string

The contact’s job title at the company (e.g. "Head of Talent Acquisition", "HR Business Partner").

string | null

LinkedIn profile URL, when found.

string | null

Work email. Only populated when reveal_email was set and one was found.

string | null

Verification status of the email (e.g. verified, likely). With reveal_email only.

string | null

Direct phone number in E.164 form, mobile preferred. Only populated when reveal_phone was set and one was found.

object[] | null

Every number found (sanitized_number, type, status). With reveal_phone only.

string | null

Profile photo URL, when found.

string

legal, hr, recruiting, executive or other, classified from role. The same values the functions filter takes.

string

How the person relates to the role. Contacts are returned in this order:

Value	Who
`hiring_manager`	The person the role reports to. When the posting names a reporting line (“reports to the Director of Engineering”), it is whoever holds that title.
`function_leader`	A leader of the team or function the role sits in (head, director, VP).
`recruiter`	A recruiter or talent acquisition partner.
`hr`	HR, people operations or an HR business partner.
`executive`	A company executive outside the function (CEO, COO, founder), usually at smaller employers.
`other`	Anyone else linked to the role.

The same values the relationships filter takes.

object

Only when you sent functions, relationships or exclude: { "found": n, "function": a, "relationship": b, "excluded": c }. found is how many people the research found; the others are how many each filter and your list removed.

object

{ "email": n, "phone": m } - how many emails and phone numbers were found and billed for this task.

Example

1. Start the extraction

curl -X POST "https://api.hirebase.org/v2/jobs/contacts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "job_id": "6a2b0fbcfdd7c562727feab5" }'

Response — task created

{
  "id": "b707c405-e697-4c31-9261-de65a134e823",
  "type": "contacts_extraction",
  "state": "queued",
  "progress": 0.0,
  "user_id": "6678eefb1d5870366fade012",
  "input": { "job_id": "6a2b0fbcfdd7c562727feab5" },
  "created_at": "2026-06-28T03:38:27.700328",
  "updated_at": "2026-06-28T03:38:27.700342",
  "started_at": null,
  "completed_at": null,
  "error": null
}

2. Poll for the result

curl -X GET "https://api.hirebase.org/v2/tasks/b707c405-e697-4c31-9261-de65a134e823" \
  -H "x-api-key: YOUR_API_KEY"

Response — finished

{
  "id": "b707c405-e697-4c31-9261-de65a134e823",
  "type": "contacts_extraction",
  "state": "finished",
  "progress": 1.0,
  "user_id": "6678eefb1d5870366fade012",
  "worker_id": "ray_ContactsExtractionTask-bc5a1a78-...",
  "priority": 0,
  "input": { "job_id": "6a2b0fbcfdd7c562727feab5" },
  "created_at": "2026-06-28T03:38:27.700000",
  "updated_at": "2026-06-28T03:43:09.250000",
  "started_at": "2026-06-28T03:38:32.308000",
  "completed_at": "2026-06-28T03:43:09.250000",
  "error": null,
  "result": {
    "contacts": [
      {
        "name": "Jane Doe",
        "role": "Director of Engineering, Payments",
        "profile_url": null,
        "email": null,
        "photo_url": null,
        "function": "other",
        "relationship": "hiring_manager"
      },
      {
        "name": "Francisco Lopez",
        "role": "Head of Talent Acquisition",
        "profile_url": "https://linkedin.com/in/frankjlpz",
        "email": null,
        "photo_url": null,
        "function": "recruiting",
        "relationship": "recruiter"
      },
      {
        "name": "Adam Kelly",
        "role": "HR Business Partner",
        "profile_url": "https://linkedin.com/in/adam-kelly-79263698",
        "email": null,
        "photo_url": null,
        "function": "hr",
        "relationship": "hr"
      }
    ],
    "reveals": { "email": 0, "phone": 0 }
  }
}

Timing: a posting researched for the first time takes a few minutes (about 8 minutes at the median); one already researched returns in seconds. 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.

Why a task failed

A failed task (state: "failed") is never charged. Use error_code to decide what to do next; error carries the same reason in words.

`error_code`	Meaning	`retryable`	What to do
`no_contacts_found`	The research ran and found no one publicly linked to the role at this employer.	`false`	Move on. The same posting returns the same answer for the next 7 days.
`no_matching_contacts`	People were found, but your `functions` or `relationships` filter or `exclude` list removed every one of them. The `error` says how many each removed.	`false`	Move on, or widen `functions` / `relationships`.
`job_expired`	The posting expired more than 30 days ago and was never researched.	`false`	Move on, or submit a current posting from the same employer.
`job_not_found`	No live or archived posting has this id. Normally caught at submit with a `404`.	`false`	Check the id.
`temporary`	A temporary error on Hirebase’s side or with an upstream provider.	`true`	Submit the same `job_id` again after a short wait.
`internal`	An unexpected error on Hirebase’s side.	`false`	Contact support with the task id if it keeps happening.

Response — failed

{
  "id": "78c49ba2-fd09-4983-bdb2-38834d95a050",
  "type": "contacts_extraction",
  "state": "failed",
  "error": "Contacts for job 6956ccc501a43a3416e21f30 not found: the posting expired on 2026-01-01, too long ago to research the people behind it. Nothing was charged.",
  "error_code": "job_expired",
  "retryable": false,
  "result": null
}

Error Responses

401 Unauthorized

Missing or invalid API key. Body: { "detail": "Sign in to access this endpoint" } (missing key) or { "detail": "Invalid API key" }.

403 Forbidden

Your account doesn’t have the Hiring Manager API add-on. Body: { "detail": "Your current plan does not include access to this endpoint. Upgrade at /v2/billing/portal." } with header X-Billing-Code: feature_missing. Add it under Settings → Subscriptions.

402 Payment Required

Your last Hiring Manager API charge failed. Body:

{ "detail": "Your last Hiring Manager API payment failed. Update your payment method at /v2/billing/portal to continue; tasks already queued keep running.", "code": "payment_failed" }

. Update your payment method at /v2/billing/portal (or in the web app under Settings → Subscriptions); requests work again as soon as the payment goes through. Tasks you already queued keep running. Only a failed charge causes this, never unbilled usage.

404 Not Found

No live or archived posting has this job_id. Body: { "detail": "No live or archived posting has the id 'abc'. Use the _id of a Hirebase job.", "code": "job_not_found" }. No task is created and nothing is charged.

422 Unprocessable Entity

Missing or malformed job_id. Body: { "detail": [ { "type": "missing", "loc": ["body","job_id"], "msg": "Field required", "input": {} } ] }.

Task failed (state: "failed")

The research itself can still fail after the task is created. Always check the task state after polling, and use error_code and retryable to decide whether to submit again. See Why a task failed.

Notes & Best Practices

Poll, don’t block. Extraction typically takes seconds to a few minutes. Poll GET /v2/tasks/{id} every few seconds, or one List Tasks call for a whole batch; treat finished and failed as terminal. Task reads have their own budget of 600 requests per minute, so polling never uses up the 100 per minute your searches and submits share.
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.

Jobs API

Expired & Historical Jobs API

Hiring Manager API

Companies API

Insights API

Salary Benchmark API

Reference Data API

Resumes

Tasks API

Billing & Usage

Error Handling

Hiring Manager Contacts API

Endpoint

Authentication

Request Body

Response

Example

1. Start the extraction

2. Poll for the result

Why a task failed

Error Responses

Notes & Best Practices

​Endpoint

​Authentication

​Request Body

​Response

​Example

​1. Start the extraction

​2. Poll for the result

​Why a task failed

​Error Responses

​Notes & Best Practices

Endpoint

Authentication

Request Body

Response

Example

1. Start the extraction

2. Poll for the result

Why a task failed

Error Responses

Notes & Best Practices