Skip to main content
The prospecting API lets you source new contacts — a Property Manager, a VP of Operations, whoever your buying committee configuration targets — at a specific account, on demand. It runs the same buying-committee engine behind the dashboard’s “prospect additional contacts” action, so results and billing match exactly what you’d get clicking that button by hand. This is distinct from enrichment, which fills in more detail about one contact you already have. Prospecting instead finds contacts you don’t have yet at an account you specify.

​
Make a Prospecting Call

Send a POST request to /v1/prospect with the account you want to source contacts at:
account_id accepts either a company_leads UUID for an account already identified from site traffic, or a bare domain. Passing a domain that doesn’t match any existing account auto-creates a minimal account record to prospect against — unbilled, since the account itself was never actually visited or enriched.

​
Choosing Roles

With no roles in the request, Knock2 uses your tenant’s saved buying-committee configuration (the same roles configured in the dashboard’s Buying Committee settings). To search an ad-hoc list instead — for this call only, without touching your saved configuration — pass roles explicitly:
If neither the request nor your tenant configuration specifies any roles, the call returns a 400 no_roles_configured error — there’s nothing to search for.

​
Response and Billing

A successful call returns which contacts were newly found versus already on file, and what was billed:
Billing is 2 credits per newly found contact (credits_charged is always 2 × contacts_found). A run that finds nothing new — every matching contact was already on file — costs nothing.
Some contacts may arrive slightly after the response comes back, since results from certain vendors are queued rather than returned inline for this endpoint. Poll GET /v1/contacts filtered by account_id a moment later to pick up any stragglers.

​
Locked Accounts

An account that Knock2 has identified but that your plan hasn’t yet revealed (see Accounts) cannot be prospected — the call returns 403 locked. Reveal the account first, either in the dashboard or via your plan’s reveal allowance, then retry.

​
Required Scope

Your API key needs the prospecting:write scope (or the broader all:write scope). This scope is not granted automatically to keys provisioned for child tenants — unlike most default scopes, a spend-capable scope like this one has to be selected explicitly. See the Prospect Contacts API reference for the complete request/response shape and error codes.