Enrich people

Send a batch of people by email. For each person Knock finds, you get their name, title, seniority, LinkedIn profile, location and their full company profile.

POST https://app.knock-ai.com/v1/enrichment-requests/people

Request bodyCopy Anchor Link

{
  "people": [
    { "email": "jane@acme.com", "firstName": "Jane", "lastName": "Doe" },
    { "email": "bob@globex.com" }
  ]
}

Validation is all-or-nothing: if any entry is invalid, the API answers 400 with code validation, lists every problem, and submits nothing. Fields the API doesn't know are ignored.

Submit the requestCopy Anchor Link

curl -X POST https://app.knock-ai.com/v1/enrichment-requests/people \
  -H "x-api-key: $KNOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people": [
      { "email": "jane@acme.com", "firstName": "Jane", "lastName": "Doe" },
      { "email": "bob@globex.com" }
    ]
  }'

Knock resolves each person while it handles your POST, so a full batch of 100 people takes longer to answer than a single person. Give the call a generous client timeout.

ResponseCopy Anchor Link

{
  "enrichRequestId": "7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14",
  "status": "in_progress"
}

The status isn't always pending: people Knock can answer straight away are final in the 202 response already.

What happens to each personCopy Anchor Link

Knock lowercases each email and collapses repeated emails into one item. Trim emails before sending: an email with surrounding spaces is rejected as invalid and fails the whole batch. Then, for each distinct person:

A pending person finishes when enrichment does. If Knock already holds a profile that needs refreshing, the item stays pending until the refreshed data is in, so you never get data that's about to change.

Every submitted person also becomes a contact in your Knock account, whether or not enrichment finds them. Submitting the same email again reuses that contact.

What you get backCopy Anchor Link

Read the request with GET /v1/enrichment-requests/{enrichRequestId}. A completed person item looks like this:

{
  "input": "jane@acme.com",
  "status": "completed",
  "result": {
    "firstName": "Jane",
    "lastName": "Doe",
    "title": "VP Sales",
    "seniority": "VP",
    "profession": "Sales",
    "linkedinUrl": "https://linkedin.com/in/janedoe",
    "location": "Austin, Texas, United States",
    "photoUrl": null,
    "currentPositionStartDate": "2024-03",
    "company": {
      "name": "Acme",
      "domain": "acme.com",
      "industry": "COMPUTER_SOFTWARE",
      "size": "101-200"
    }
  }
}

The company above is shortened. It's the full company result, the same object a company request returns, or null while the person's company isn't resolved yet.

• input is the email as Knock normalized it, so Jane@Acme.com comes back as jane@acme.com. Match results to your records by this value.
• A person result always has a linkedinUrl: Knock only returns a person once it has matched them to a LinkedIn profile.
• Every key is always present. Fields Knock has no data for are null.

See Person result for every field.

ErrorsCopy Anchor Link

Authentication, permission and rate-limit errors apply too. See Errors for the full list and the API reference for the complete schema.