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
Titles to look for, for example
["VP Marketing", "Head of Growth"]. Each up to 100 characters. Send roles, seniority, or both.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.Response
One plain sentence: how many people were found, the charge, and why the search stopped early if it did.
Why candidates were left out, as reason and count. For example
person_already_delivered, person_name_hidden_by_source, no_email.Set when the search stopped at one of Agentic ID’s own limits on paid sources. See What it costs.
What it costs
quoted_creditsis 2 timeslimit, ormax_creditsif that is lower.max_creditsis 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 readableseniority, or both. exclude_seenis on by default. Asking again returns different people, because those already delivered to your workspace are skipped and counted inexcludedasperson_already_delivered. Set it tofalseto 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
excludedasperson_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 withemail_. - Fewer than
limitis normal. One call looks at a limited number of candidates.excludedsays why the rest were left out. - One company per call. For people across many companies, use Discover with
contact_filters.

