Enrichment and Prospecting

These endpoints bring data from a data provider into your workspace. Enrichment fills in contacts and companies you already have. Prospecting finds people at companies you already track, or searches the provider’s database for companies and people you do not have yet and saves the matches as records.

Two providers can run a call: Apollo and Hunter. You never name one. Pathbound picks the workspace’s connected provider, and every response says which one ran in via.

Before the first call, connect Apollo or Hunter under Integrations, have a workspace admin turn on the switch for the kind of work under MCP Tools → Apollo or MCP Tools → Hunter, and use an API key that has the enrichment:write scope. The MCP tools enrich_contacts, enrich_companies, find_people_at_companies, prospect_people and prospect_companies call these endpoints (tools reference).

enrichment:write is opt-in. A key has it only when it was selected at creation, and a key created without any scopes does not have it.

A workspace admin decides what each provider may be used for. Each provider has three switches under MCP Tools:

The API reads these switches on every call and for every caller. A REST API key is held to them exactly as an MCP connection is. The MCP server also reads them to decide which tools it lists. When no connected provider has the switch on for the kind of work you ask for, the call is answered 412 and nothing is spent.

When both providers are connected and both allow the kind of work, Apollo runs the call. To have Hunter run it, leave Apollo’s switch for that kind of work off. One provider runs a call: if it finds nothing, the other is not tried. No field names a provider, and one sent in the body is not read.

POST /v1/enrichment/contacts

Required scope: enrichment:write

Looks each contact up with the provider and merges what it returns into the contact: name, job title, LinkedIn profile URL, phone, location, company and, when the provider reveals or finds one, the email address.

curl -X POST https://api.pathbound.ai/v1/enrichment/contacts \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "665f1c2ab3d4e5f601234567",
      "665f1c2ab3d4e5f601234568",
      "665f1c2ab3d4e5f601234569"
    ]
  }'

How a contact is looked up depends on the provider:

• Apollo matches on the contact’s email, name, company and LinkedIn profile URL.
• Hunter enriches a contact that has an email from that address. For a contact without one it looks for a work address, from the LinkedIn profile URL or from the first and last name plus the company’s domain or name. A contact with none of these is skipped with insufficient_identity.

{
  "status": "success",
  "via": "apollo",
  "requested": 3,
  "enriched": 1,
  "not_found": 1,
  "skipped": 1,
  "credits_consumed": 1,
  "deliverability": "queued",
  "results": [
    {
      "contact_id": "665f1c2ab3d4e5f601234567",
      "status": "enriched",
      "email": "[email protected]",
      "email_status": "verified"
    },
    { "contact_id": "665f1c2ab3d4e5f601234568", "status": "not_found" },
    { "contact_id": "665f1c2ab3d4e5f601234569", "status": "skipped", "reason": "already_enriched" }
  ]
}

A request that reaches a provider is a 200, even when no contact was enriched. Read results to see what happened to each one.

With Hunter, when the key is refused, the credits are used up or the rate limit is reached before any contact got through, the whole call is answered with that refusal instead of a list of skipped contacts.

POST /v1/enrichment/companies

Required scope: enrichment:write

Looks each company up by its domain and merges what the provider returns into the company: name, industry, description, location, phone, employee count, annual revenue and founded year.

{
  "status": "success",
  "via": "hunter",
  "requested": 2,
  "enriched": 1,
  "not_found": 0,
  "skipped": 1,
  "credits_consumed": 0.2,
  "results": [
    { "company_id": "665f1c2ab3d4e5f6012345a1", "status": "enriched", "domain": "example.com" },
    { "company_id": "665f1c2ab3d4e5f6012345a2", "status": "skipped", "reason": "no_domain" }
  ]
}

The fields are those of Enrich Contacts, with company_id and the company’s domain on each result and no deliverability.

reason is not_found_in_pathbound, already_enriched, no_domain (the company has no domain to look up), time_budget, or one of the apollo_error: …, hunter_error: … and persist_error: … forms.

POST /v1/prospecting/people-at-companies

Required scope: enrichment:write

Finds people who work at companies already in your workspace and saves them as contacts linked to those companies. Pathbound reads each company’s domain from its record and searches the provider within that domain, in the order you gave the companies, until limit people are collected.

Company filters do not apply here. The companies are the filter, and an org_* field is not read.

curl -X POST https://api.pathbound.ai/v1/prospecting/people-at-companies \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_ids": ["665f1c2ab3d4e5f6012345a1"],
    "titles": ["head of operations", "vp of operations"],
    "limit": 5,
    "tags": ["campaign:ops-leaders"]
  }'

The two providers work differently:

• Apollo searches for free and charges for each email it reveals. A person your workspace already got from Apollo and holds an email for is skipped before anything is revealed, and counted in existing_skipped. With reveal_emails: false people are saved without an email at no cost. A later call with reveals on reveals those same people.
• Hunter returns people together with their addresses, up to 10 per company, and charges per company that has matches. With reveal_emails: false it searches nothing, spends nothing and returns no one. It cannot skip people before it charges, so existing_skipped is always 0. A person already in your workspace comes back with created: false.

{
  "status": "success",
  "via": "apollo",
  "mode": "anchored",
  "companies": [
    {
      "company_id": "665f1c2ab3d4e5f6012345a1",
      "domain": "example.com",
      "found": 2,
      "created": 2,
      "existing": 0
    }
  ],
  "contacts": [
    {
      "contact_id": "670a3b4c5d6e7f8091a2b3c4",
      "company_id": "665f1c2ab3d4e5f6012345a1",
      "provider_person_id": "5f2a9c1e8b3d4a0001c7e9b2",
      "name": "Ada Lovelace",
      "title": "VP of Operations",
      "email": "[email protected]",
      "email_status": "verified",
      "created": true
    }
  ],
  "requested_limit": 5,
  "search_total": null,
  "existing_skipped": 0,
  "companies_created": 0,
  "unlinked": 0,
  "credits_consumed": 2,
  "deliverability": "queued",
  "tags_applied": ["campaign:ops-leaders"],
  "note": "Contacts saved. Email deliverability (Emailable) is being checked in the background …"
}

POST /v1/prospecting/people

Required scope: enrichment:write

Searches the provider’s database for people by who they are and by what kind of company they work at, and saves the matches as contacts. Each person’s employer is matched to a company in your workspace by its domain, or created, and the contact is linked to it.

At least one company filter is required. A search by person filters alone is refused with 400 unanchored_requires_org_filter.

{
  "titles": ["head of sales"],
  "org_keywords": ["field service"],
  "org_employee_ranges": ["11,50", "51,200"],
  "org_locations": ["United States"],
  "limit": 10,
  "tags": ["icp:field-service"]
}

On this endpoint locations and keywords describe the person. The company’s are org_locations and org_keywords.

The two providers work differently here too:

• Apollo runs one free search and reveals up to limit of the people it finds, passing over those your workspace already got from Apollo with an email (existing_skipped). search_total is the number of people who match in Apollo’s database. A person whose employer has no domain is saved without a company and counted in unlinked.
• Hunter first finds companies that match the company filters, for free, then looks for people inside up to 15 of them and takes up to 3 from each. search_total is null, and note says how many companies matched.

The response has the shape of Find People at Companies, with mode: "unanchored". companies lists the employers of the people saved, each with company_created.

POST /v1/prospecting/companies

Required scope: enrichment:write

Searches the provider’s database for companies and saves the matches as companies in your workspace. A company you already have, matched by domain, is returned with created: false and left as it is.

At least one filter is required. A request without one is refused with 400 requires_org_filter.

curl -X POST https://api.pathbound.ai/v1/prospecting/companies \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["field service"],
    "employee_ranges": ["11,50", "51,200"],
    "locations": ["United States"],
    "limit": 25,
    "tags": ["icp:field-service"]
  }'

{
  "status": "success",
  "via": "apollo",
  "search_total": 1840,
  "requested_limit": 25,
  "found": 25,
  "created": 22,
  "existing": 2,
  "companies": [
    {
      "company_id": "670a3c5d6e7f8091a2b3c4d5",
      "provider_company_id": "5e66b6381e05b4008c8331b8",
      "domain": "example.com",
      "name": "Example Field Services",
      "created": true,
      "saved_in_provider": false
    }
  ],
  "skipped": [
    { "provider_company_id": "5e66b6381e05b4008c8331c9", "name": "Example Holdings", "reason": "no_domain" }
  ],
  "credits_consumed": 1,
  "tags_applied": ["icp:field-service"],
  "note": "Saved 22 new prospect companies (2 already in Pathbound). …"
}

The call returns one page of results. To get different companies, change the filters.

On Apollo this search needs an Apollo connection made after September 11, 2026. An older connection is answered 412 scope_missing: reconnect Apollo under Integrations.

With enrich: true, the search and the save happen first. If the enrichment step is then refused for the daily budget, the call is answered 429 although the companies were already saved.

A filter that the provider running the call cannot express is refused before anything is spent. It is never dropped, because a dropped filter widens the search and you would pay for the wider result. The same goes for a filter value the provider cannot express exactly.

Up to 50 values are read from each list (employee_ranges 20, domains 100), and values past that are not read. A company list of more than 100 values is a 400.

Every entry of a list has to be a string. An entry of another type is not read and raises no error, so "employee_ranges": [[11, 50]] is an empty filter, and a search that has other filters then runs without it. Check the types you send: this is the one case in which a filter can go missing.

On POST /v1/prospecting/companies the fields are written as below. On POST /v1/prospecting/people each takes the org_ prefix (org_employee_ranges, org_locations, and so on), and name is not available.

Apollo can express every filter above. Hunter cannot. When Hunter is the provider for a call, these are refused:

• Person keywords, days_in_title_min, days_in_title_max. Not supported. The call is refused with 400 unsupported_filters.
• employee_ranges. Hunter has fixed company sizes: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000 and 10001+. A range must start and end on those edges: "11,50" and "51,500" are accepted, "20,100" is not. For no upper bound, end the range at 1000000 or more, as in "10001,1000000".
• seniorities. Only junior, senior and executive. Name specific roles with titles instead.
• departments. Only executive, it, finance, management, sales, legal, support, hr, marketing, communication, education, design, health, operations, product, research, consulting, administrative and procurement. Engineering roles are under it.
• locations, the company’s and the person’s. Hunter takes a country by name or ISO code ("Germany", "FR"), a US state ("California"), a city with its country or state ("Berlin, Germany", "Austin, Texas"), a continent ("Europe"), or one of the regions AMER, EMEA, APAC and LATAM. A city on its own is refused, and so is a name that is both a US state and a country: write "Georgia, US" for the state.
• hiring_posted_after. Hunter filters job postings by the last 7, 30 or 90 days only. Your date is applied as the widest of those windows that fits inside it, so the search is never wider than you asked, and note says which window was used. A date less than 7 days back is refused.
• name together with domains. Refused. Search by one or the other.
• technologies. Needs a paid Hunter plan. Without one the call is answered 412 plan_required.

A value Hunter cannot express is refused with 400 unsupported_filter_value. The error names the filter and the value in details, and its hint says what Hunter accepts.

• A record is matched before it is created. A company is matched by its domain. A person is matched by email address or LinkedIn profile URL. A match is returned with created: false.
• A company is only ever created from a domain. A company the provider returns without one is never saved.
• A person found at a company is linked to that company.
• lifecyclestage is written on records the call creates, never on one you already had. A lead or a customer is not turned back into a prospect. The allowed values are prospect, subscriber, lead, mql, sql, opportunity, customer, evangelist and other.
• tags are written on the contacts and companies the call creates. On Apollo a contact you already had that the call returns is tagged too. Tags are trimmed, lowercased and cut to 64 characters, and at most 50 are read. Use a tag to get the batch back later with tags_any on GET /v1/contacts or GET /v1/companies.
• Every value is merged into the record with the provider as its source (apollo or hunter), next to what your other sources say. Read it in the record’s unified profile.
• On Hunter a contact you already had keeps its own email address. One that had none receives the address Hunter found.

Every response that can add email addresses reports deliverability:

Hunter’s own status becomes the verdict on the contact this way: valid is deliverable, invalid is undeliverable, and accept_all and disposable are risky. Any other status leaves the address without a verdict, for Emailable to check.

GET /v1/contacts filters on the verdict with email_verification_state.

When a person has asked Hunter to stop processing their data, the contact is reported skipped with the reason claimed_email, nothing Hunter said about them is kept, and the contact is never sent to Hunter again. If a later search returns that person, the contact is left untouched and note counts them.

Per call: 25 contacts or companies to enrich, 25 companies to look inside, 25 people to save, 50 companies to save.

Per day: the calls of a workspace, over REST and MCP together, may spend a set number of credits with each provider a day, counted in UTC. The budget is there so that a loop cannot empty your account with the provider. A call whose most expensive outcome would pass it is refused with 429 and the code APOLLO_AGENT_BUDGET or HUNTER_AGENT_BUDGET. details.cap is the budget and details.spent is what was used so far. Nothing is spent by a refused call, and credits a call reserved and did not use are given back. If the budget is too low for your work, write to [email protected].

What each provider charges, in its own credits:

credits_consumed on Apollo is what Apollo reported for the call, or the number of matches when Apollo reports nothing. On Hunter it is counted from the prices above. Hunter bills a repeated search once per billing period, so its real charge can be lower.

These endpoints take no Idempotency-Key: a repeated call runs again. A contact or company that was already enriched is skipped unless you set force, and on Apollo a person your workspace already got from it with an email is not revealed twice. An Apollo company search costs its credit every time.

For the API’s own request limits, see Rate limits.

Checks run in this order, and a call stops at the first one it fails:

1. The API key and its scope.
2. The shape of the request: types, limits, the form of an ID, an employee range or a date, and a search with no company filter. This answer does not depend on which provider is connected or which switches are on.
3. Whether a provider may run the call: connected, and its switch for this kind of work on.
4. Whether that provider can express every filter and every filter value.
5. The day’s budget, before each step that costs credits.

An error has the shape { "status": "error", "error": "…", "code": "…" }, with a hint and details where the table names them. See Errors for the answers every endpoint shares.

When no provider may run the call, the 412 names the reason that is closest to working: a switch that is off, before credentials that were refused, before a provider that is not connected.

These endpoints take up to 25 records a call. To enrich every member of a saved segment as a background job, use POST /v1/segments/:ref/actions with the action apollo_enrich. That job always runs on Apollo, under Apollo’s Enrichment switch, and draws on the same daily budget.

Apollo watches the contacts saved in your Apollo team and records when one changes title or employer. Pathbound reads that from Apollo at no credit cost and writes it on the contact: job_changed_at, previous_jobtitle and previous_company, with jobtitle and company updated to the new values, plus the tag signal:job-change.

To get those contacts, call GET /v1/contacts with tags_any=signal:job-change. Contacts at the prospect stage are checked again about every 30 days once a workspace admin turns on Refresh prospects under Integrations → Apollo.

Four older routes remain for existing callers. New code should use the endpoints above.

They take the same request fields and the same scope. They always run on Apollo, under Apollo’s switches, and never on Hunter. Their responses carry no via and use Apollo’s names: apollo_person_id, apollo_organization_id and saved_in_apollo in place of provider_person_id, provider_company_id and saved_in_provider.