Quickstart
Verify your API key, submit your first enrichment request and read the results in a few minutes.
The Knock API lets your own systems enrich people and companies with the same data Knock uses in the product. You send a batch of emails or domains, Knock enriches them in the background, and you read the results when they're ready.
This guide takes you from an API key to your first enriched person. Every request goes to:
https://app.knock-ai.comEnrichment requests are billable
Submitting people or companies starts real enrichment: it consumes enrichment credits from your Knock account, and every person you submit is added to your Knock contacts. There is no sandbox mode, so start with one or two records you actually want enriched.
Make your first request
Get an API key
Ask your Knock account team, or your shared Slack channel with Knock, for an API key with the Enrichment API role. Store it in an environment variable on the server that will call the API:
export KNOCK_API_KEY="KNK-..."Keep the key on your backend. Never put it in browser or mobile code. See Authentication for roles, rotation and the errors you can get.
Verify the key
Call the verify endpoint. It's free (no credits) and returns the ID of the Knock account the key belongs to.
curl https://app.knock-ai.com/resources/whoami/v1 \
-H "x-api-key: $KNOCK_API_KEY"{
"vendorId": "3f6a2b1c-8d4e-4f5a-9b6c-7d8e9f0a1b2c"
}A 401 with code authentication.invalid means the key is missing, wrong or expired. You can also try the key in your browser on the Authentication page; if your browser can't reach the API from there, it shows the same check as a terminal command.
Submit people for enrichment
Send up to 100 people per request. Only email is required. firstName and lastName are optional: Knock uses them as the contact's name when it adds the person to your contacts; they don't affect matching.
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" }
]
}'The API answers 202 Accepted with the ID of your new enrichment request:
{
"enrichRequestId": "7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14",
"status": "pending"
}Save enrichRequestId. There is no endpoint that lists your requests, so this ID is the only way to read the results.
Poll for the results
Read the request until its status is final: completed, partially_completed or failed. While it's pending or in_progress, wait and read again.
curl https://app.knock-ai.com/v1/enrichment-requests/7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14 \
-H "x-api-key: $KNOCK_API_KEY"Reading a request never starts new enrichment, but every read counts toward your rate limit. Start with a few seconds between reads and back off from there; Get results has a ready-to-use polling function.
Read the enriched person
Each item has the input you sent, its own status, and a result once the item is completed:
{
"enrichRequestId": "7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14",
"type": "people",
"status": "completed",
"createdAt": "2026-10-20T09:15:02.418Z",
"items": [
{
"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",
"country": "US"
}
}
}
]
}The company object above is shortened. A person's company carries the full company profile, the same object a company request returns. See Get results for every field.