Skip to main content
POST /v1/find answers: who holds this role at this company? Name one company and the titles or seniority you want, and get back people with a work email that passed verification. Use it when you know the account and need the contact. To find new companies, use Discover.
200
Emails are returned masked today: the first character and the domain are kept.

Request

object
required
The company to search in. Send id or domain.
string[]
Titles to look for, for example ["VP Marketing", "Head of Growth"]. Each up to 100 characters. Send roles, seniority, or both.
string | string[]
Seniority to look for, for example "director+" or ["vp", "c_suite"].
string[]
Where the person is. This is the person’s location, not the company’s headquarters.
integer
default:"5"
The most people to return. 1 to 25.
boolean
default:"true"
Skip people already delivered to your workspace by Find or Discover.
string
default:"b2b_outbound"
Why you are asking. One of b2b_outbound, ad_audience, own_customer_enrichment, fraud_check. The call is refused if your workspace has not allowed the purpose.
integer
required
The most this call may charge. 0 to 100000. Never charged past it.

Response

string
required
The ID of this call. The same value as the X-Request-Id header.
string
required
One plain sentence: how many people were found, the charge, and why the search stopped early if it did.
object
required
string
The Agentic ID of the company that was searched.
object[]
required
The people delivered.
object
required
Why candidates were left out, as reason and count. For example person_already_delivered, person_name_hidden_by_source, no_email.
object[]
required
Filter values that could not be read. They are returned, never silently dropped.
string
Set when the search stopped at one of Agentic ID’s own limits on paid sources. See What it costs.

What it costs

  • quoted_credits is 2 times limit, or max_credits if that is lower.
  • max_credits is required. The search stops when the next person would not fit under it.
  • If your balance covers only part of the request, the part it covers is delivered.
stopped_early values. In every case nothing is charged for what was not delivered. See Credits for how holds and charges work.

Errors

See Errors for the full list.

Behaviour

  • A role is required. Send roles, a readable seniority, or both.
  • exclude_seen is on by default. Asking again returns different people, because those already delivered to your workspace are skipped and counted in excluded as person_already_delivered. Set it to false to get them again; they are charged again.
  • People need a full name or a profile link. A candidate is only usable if an email can be looked up for it, which needs a first and last name or a profile link. Candidates without either are counted in excluded as person_name_hidden_by_source.
  • Only people with an email that passed verification are delivered. A candidate with no email is counted as no_email. One whose email did not pass is counted under a reason starting with email_.
  • Fewer than limit is normal. One call looks at a limited number of candidates. excluded says why the rest were left out.
  • One company per call. For people across many companies, use Discover with contact_filters.