Build a Prospecting Search

From an ICP (ideal customer profile) definition to a contact-ready list, spending credits on enrichment only for people who survive qualification.

Step paths below are relative — every request also needs the version and environment prefix, https://api.aggknowledgeai.com/v2/{environment}. So POST /person/enrich is called at https://api.aggknowledgeai.com/v2/test/person/enrich. See Environments.
1
Translate the ICP into filters
Function and seniority → workExperience.role/seniority; account profile → company.* firmographics; “uses competitor X” → vendorgraphics.aggkProductId (catalog IDs from Product Catalog).
2
Validate the requestPOST /discover/people/advanced/validate
Free, and catches filter mistakes before they cost anything.
3
Count, then iteratePOST /discover/people/advanced/count
Tighten or loosen filters until the population is workable. Counts are cheap; treat this as your tuning loop.
4
Discover peoplePOST /discover/people/advanced
Page through results with cursor pagination.
5
Qualify on summaries
Score and rank with the summary fields before enriching anything.
6
Enrich the survivorsPOST /person/enrich
By personId (tier 1), then Request contact info (async) for the final qualified set only — see Retrieve Contact Info at Scale.

The tuning loop in practice#

cURL — Count results
curl --request POST \
  --url https://api.aggknowledgeai.com/v2/live/discover/people/advanced/count \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "workExperience": {
      "role": { "or": ["engineering"] },
      "seniority": { "or": ["vp", "cxo"] }
    },
    "company": {
      "employeeCountRange": { "or": ["201-500", "501-1000"] }
    }
  }'
Response
{ "count": 14823, "isSuccess": true }

~15k is too broad for a focused campaign — add a location filter or an industry list and re-count. When the number matches your capacity, switch the same body to Discover people.

Warning: Discover pages through at most 5,000 results per search, even when the count is far higher. Use Count for the true population size, but narrow your filters (metro, industry, a company list) until the set you actually page through fits under the cap — otherwise everyone past result 5,000 is silently unreachable.
Warning: Don’t enrich an entire Discover result set by default. Summaries are enough for scoring; full enrichment is for the shortlist. This ordering is the difference between hundreds and tens of thousands of credits spent on enrichment.