POST /v1/enrich — Enrich a Contact by Email or LinkedIn URL

POST /v1/enrich runs an email address and/or LinkedIn URL through Knock2’s enrichment waterfall — querying multiple sources in sequence and merging the results into a single unified contact profile. You get back fields like job title, seniority, department, and company details in one call. Each successful enrichment costs 1 credit from your account balance, so Knock2 only charges you when data is actually found.

Endpoint

POST https://api.knock2.ai/v1/enrich

Request Body

At least one of email or linkedin_url is required.

string

The email address of the contact you want to enrich. Must be a valid email format.

string

The LinkedIn profile URL for the contact (e.g. https://linkedin.com/in/janesmith). Can be used on its own to enrich a contact with no email on file, or provided alongside email to improve match quality.

Example Request

curl -X POST https://api.knock2.ai/v1/enrich \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.smith@acme.com", "linkedin_url": "https://linkedin.com/in/janesmith"}'

Response

A successful request returns 200 OK with an EnrichResponse body.

{
  "status": "enriched",
  "contact_id": "cnt_01HX...",
  "data": {
    "first_name": "Jane",
    "last_name": "Smith",
    "title": "VP of Engineering",
    "email": "jane.smith@acme.com",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "seniority": "vp",
    "departments": ["engineering"]
  }
}

string

Indicates whether enrichment succeeded. See status values below.

string

The Knock2 contact identifier for the enriched person. Present when status is enriched.

string

The contact’s first name.

string

The contact’s last name.

string

The contact’s job title.

string

The email address that was enriched, echoed back in the response.

string

The name of the company the contact is associated with.

string

The primary domain of the contact’s company.

string

The contact’s seniority level (e.g. vp, director, manager, ic).

array of strings

The functional departments the contact belongs to (e.g. ["engineering"], ["sales", "marketing"]).

Status Values

Status	Meaning
`enriched`	Data was found — the `data` object is populated. 1 credit is deducted.
`not_found`	No sources in the enrichment waterfall returned a match. No credit is deducted.

Credits

Each call that returns status: enriched costs 1 credit. Calls that return not_found are free. If your account has reached its credit limit, Knock2 returns a 402 error. You can view your remaining credits and purchase additional ones in the Knock2 dashboard.

Required Scope

This endpoint requires the enrichment:write scope (or the broader all:write scope) on your API key. Keys that lack this scope receive a 403 error.

Error Responses

Status	Meaning
`401`	Missing or invalid API key.
`402`	Credit limit reached, or workspace deactivated. Add more credits or reactivate in the Knock2 dashboard to continue enriching contacts.
`403`	Your API key does not have the `enrichment:write` scope required for this endpoint.
`422`	Neither `email` nor `linkedin_url` was provided, or `email` is not a valid email address.
`429`	Rate limit exceeded. Slow down your request rate and retry.

Overview

Accounts

Contacts

Activity & Scores

Filter Sets

Webhooks

Enrichment & Auth

Tenants & Script

POST /v1/enrich — Enrich a Contact by Email or LinkedIn URL

Endpoint

Request Body

Example Request

Response

Status Values

Credits

Required Scope

Error Responses

​Endpoint

​Request Body

​Example Request

​Response

​Status Values

​Credits

​Required Scope

​Error Responses

Endpoint

Request Body

Example Request

Response

Status Values

Credits

Required Scope

Error Responses