Skip to main content
POST /v1/discover answers: which companies match these filters, and who works there? Send account filters and, if you want people too, contact filters. Use it to build a new list. Use count_only first to see how many companies match before anything is delivered.
200
Emails are returned masked today: the first character and the domain are kept.

Request

object
required
Which companies to look for. At least one readable filter is needed.
object
Send this to also get people inside the companies delivered. Needs job_title or a readable job_level.
integer
default:"25"
The most companies to deliver. 1 to 500.
boolean
default:"true"
Skip companies and people already delivered to your workspace.
boolean
default:"false"
When true, nothing is delivered and nothing is charged. The reply says how many companies match and which source would be asked.
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
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: what was delivered, what was charged, and why fewer came back than asked if that happened.
object
required
object[]
required
The companies delivered. Empty on a count.
object[]
required
The people delivered. Empty without contact_filters and on a count.
object
required
Why candidates were left out, as reason and count. For example already_delivered, size_mismatch, size_unknown, country_disputed, credit_cap.
object[]
required
Filter values that could not be read, each with field and value. They are returned, never silently dropped.
object[]
required
Which source was asked and what it could filter itself, each with provider and why.
number
On a count: about how many companies match at the source.
boolean
On a count: the source did not apply every filter, so fewer will pass when delivered.
object[]
How a plain word in a filter was read, each with field, given and read_as. Check it when a word was read as something broader than you meant.
string
Why fewer companies were delivered than max_accounts, when that happened.
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 max_accounts times (1 + 2 times per_account), or max_credits if that is lower. Without contact_filters it is max_accounts.
  • When max_credits is reached the search stops. fewer_than_asked says so and excluded counts credit_cap.
  • 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

  • Count first. count_only: true returns total_at_provider, an empty accounts and contacts, and a cost of 0. When count_is_upper_bound is true, expect fewer on delivery. contact_filters is not used on a count.
  • keywords rank, keywords_required filters. By default keywords only order the results: companies that mention more of them come first. Set keywords_required: true to make every result mention one. When keywords are the only filter, they always filter.
  • Words are read, and you are told how. A plain word such as an industry name may be read as a broader category or as a description keyword. filters_read_as shows it. Check the first results before asking for many.
  • exclude_seen is on by default. Asking again with the same filters returns the next companies: those already delivered to your workspace are skipped and counted in excluded as already_delivered.
  • Fewer than max_accounts is normal. One call reads a limited number of result pages and drops candidates that fail a check. fewer_than_asked explains it. Ask again for more, or narrow the filters.
  • Size needs two sources to be charged. With a size filter, a company whose size is confirmed by only one source is delivered with size_check: "single" and charged: false.
  • People follow the same rules as Find. A person is delivered only with an email that passed verification, and only if the candidate came with a full name or a profile link.
  • Long calls. A large search can take minutes. Set your client timeout to match and send an Idempotency-Key.