POST /v1/prospect — Source New Contacts at an Account

Request

POST /v1/prospect

string

required

A company_leads UUID (an account already identified from site traffic) or a bare domain. An unknown domain auto-creates a minimal account record, unbilled.

string[]

An ad-hoc list of roles/titles to search for on this call only (e.g. ["Property Manager", "VP of Operations"]). When omitted, uses the tenant’s saved buying-committee configuration. Cleaned server-side (trimmed, deduped, capped at 10 entries).

integer

Caps how many new contacts this call will source. When omitted, uses the tenant’s configured default.

string

Prospect on behalf of a direct child tenant instead of your own. Takes precedence over ?product_slug=. See Reading a Child Tenant’s Data.

Example

curl -X POST https://api.knock2.ai/v1/prospect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acme.com",
    "roles": ["Property Manager"],
    "max_contacts": 3
  }'

Response

string

The UUID of the account that was prospected — the resolved ID even when account_id was passed as a domain.

boolean

true when account_id was an unrecognized domain and a new account record was auto-created to prospect against.

integer

Count of genuinely new contacts sourced by this run.

integer

Count of buying-committee contacts that were already on file for this account before this call.

integer

2 × contacts_found. A run that finds nothing new costs nothing.

object[]

The newly-found contacts.

Show contact fields

string

The new contact’s UUID.

string | null

The role/title query that matched this contact.

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_created": false,
  "contacts_found": 2,
  "contacts_already_existed": 3,
  "credits_charged": 4,
  "contacts": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@acme.com",
      "title": "Property Manager",
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "role_searched": "Property Manager"
    }
  ]
}

Some contacts may arrive slightly after this response — Moltsets results are queued rather than returned inline for this endpoint. Poll GET /v1/contacts filtered by account_id to pick up stragglers.

Errors

Status	`code`	Meaning
`400`	`missing_parameter`	`account_id` is missing from the request body.
`400`	`no_roles_configured`	No `roles` were passed and no buying-committee roles are configured for this tenant. Configure roles in Settings → Buying Committee, or pass `roles` explicitly on the call.
`402`	`credit_limit_exceeded`	Website or contact identification credits are exhausted for the billing period.
`402`	`account_inactive`	The workspace has been deactivated. This check runs on every `/v1` route, not just this one.
`403`	`forbidden`	API key is missing the `prospecting:write` scope.
`403`	`locked`	The account has been identified but not yet revealed.
`404`	`not_found`	`account_id` is a UUID that doesn’t resolve to an existing account for this tenant. A bare domain never 404s — it auto-creates instead.

Requires the prospecting:write scope (or the broader all:write scope). This scope is not granted by default to keys provisioned for child tenants — a parent must explicitly select it when creating a key.

Overview

Accounts

Contacts

Activity & Scores

Filter Sets

Webhooks

Enrichment & Auth

Tenants & Script

POST /v1/prospect — Source New Contacts at an Account

Request

Example

Response

Errors

​Request

​Example

​Response

​Errors

Request

Example

Response

Errors