Endpoint
GET https://api.knock2.ai/v1/contacts/{contact_id}
Required Scope
Your API key must have thecontacts:read scope (or the broader all:read scope) to call this endpoint.
Path Parameters
string
required
The unique Knock2 identifier of the contact to retrieve (e.g.
cnt_01HX...). You can obtain this ID from the List Contacts endpoint or from a webhook payload. Email addresses are not accepted as a path parameter — use the email query parameter on the List Contacts endpoint for email-based lookups.Request Parameters
string
Read a direct child tenant’s contact instead of your own (multi-tenant partners only). The
X-Knock-Tenant header takes precedence if both are supplied. See Reading a Child Tenant’s Data.string
Same as
product_slug above, as a header instead of a query param. Naming a slug that isn’t a direct child of your key returns 404, never 403.Example Request
curl https://api.knock2.ai/v1/contacts/cnt_01HX... \
-H "Authorization: Bearer YOUR_API_KEY"
Response
Returns200 OK with a data object containing the full contact record.
Example response
{
"data": {
"id": "cnt_01HX...",
"first_name": "Jane",
"last_name": "Smith",
"name": "Jane Smith",
"title": "Head of Engineering",
"email": "jane@acme.com",
"business_email": "jane@acme.com",
"personal_email": null,
"linkedin_url": "https://www.linkedin.com/in/janesmith",
"seniority": "Director",
"departments": ["Engineering"],
"phone_numbers": ["+14155550100"],
"address_city": "San Francisco",
"address_state": "CA",
"address_zip_code": "94105",
"address_country": "US",
"location": "San Francisco, CA, US",
"match_type": "email",
"is_qualified": true,
"is_business_email_valid": true,
"business_email_last_validated_at": "2024-05-01T00:00:00Z",
"last_enriched_at": "2024-05-20T11:00:00Z",
"company_id": "acc_01HX...",
"company_name": "Acme Corp",
"company_domain": "acme.com",
"company_linkedin_url": "https://www.linkedin.com/company/acme-corp",
"company_industry": "Software",
"company_sector": "Technology",
"company_description": "Acme Corp builds enterprise workflow automation tools.",
"company_estimated_employee_count": "51-200",
"company_employees_min": 51,
"company_employees_max": 200,
"company_estimated_annual_revenue": "10M-50M",
"company_annual_revenue_min": 10000000,
"company_annual_revenue_max": 50000000,
"company_phone_numbers": [],
"company_tags": ["enterprise"],
"company_technology_tags": ["Salesforce", "HubSpot"],
"company_address_city": "San Francisco",
"company_address_state": "CA",
"company_address_zip_code": "94105",
"company_address_country": "US",
"company_location": "San Francisco, CA, US",
"company_last_funding_date": "2023-09-01",
"company_last_funding_round_type": "Series B",
"company_last_funding_amount": "25M",
"crm_deal_source": "Inbound",
"crm_deal_name": "Acme Corp — Enterprise",
"crm_deal_stage": "Proposal",
"crm_deal_value_usd": 48000,
"crm_deal_close_datetime": "2024-09-30T00:00:00Z",
"crm_deal_owner_email": "alice@yourcompany.com",
"crm_deal_owner_first_name": "Alice",
"crm_deal_owner_last_name": "Johnson",
"crm_company_owner_email": "alice@yourcompany.com",
"crm_company_owner_first_name": "Alice",
"crm_company_owner_last_name": "Johnson",
"hubspot_company_id": "1234567890",
"salesforce_account_id": "0015g00000AbCdEf",
"latest_visit_datetime": "2024-06-01T14:23:00Z",
"latest_visit_page": "/docs/api",
"page_visits": [
{
"page": "/docs/api",
"start_time": "2024-06-01T14:20:00Z",
"end_time": "2024-06-01T14:23:45Z"
},
{
"page": "/pricing",
"start_time": "2024-06-01T14:15:00Z",
"end_time": "2024-06-01T14:19:50Z"
}
],
"total_browsing_time_seconds": 940,
"utms": {},
"document_referrer": "https://www.google.com",
"utm_source": "google",
"utm_medium": "organic",
"utm_campaign": null,
"utm_term": null,
"utm_content": null,
"icp_scoring_icp_id": "icp_01HX...",
"icp_scoring_icp_title": "Enterprise Engineering Leader",
"icp_scoring_score": 87,
"icp_scoring_reason": "Matches target industry, seniority, and department.",
"external_id": "their-session-id",
"external_ids": { "external_id": "their-session-id", "user_id": "u_42" },
"created_at": "2024-05-20T11:00:00Z"
}
}
Response Fields
object
required
The full contact record.
Show Contact object fields
Show Contact object fields
string
The unique Knock2 identifier for this contact.
string
The contact’s first name.
string
The contact’s last name.
string
The contact’s full display name.
string
The contact’s job title (e.g.
"Head of Engineering").string
The contact’s primary email address, if identified.
string
The contact’s work email address.
string
The contact’s personal email address, if available.
string
URL to the contact’s LinkedIn profile.
string
The seniority level of the contact’s role (e.g.
"Director", "VP", "C-Suite", "Manager").array
A list of functional departments the contact is associated with (e.g.
["Engineering"]).array
A list of phone numbers associated with the contact.
string
The city the contact is based in.
string
The state or province the contact is based in.
string
The postal or ZIP code for the contact’s address.
string
The country the contact is based in (ISO 3166-1 alpha-2 code, e.g.
"US").string
A human-readable location string combining city, state, and country.
string
How this contact was matched to a website visit (e.g.
"email", "ip").boolean
true if this contact has been marked as qualified based on your configured criteria.boolean
true if the contact’s business email address has been validated as deliverable.string
ISO 8601 timestamp of when the business email was last validated.
string
ISO 8601 timestamp of when this contact’s profile was last enriched.
string
The Knock2 account ID of the company this contact is associated with.
string
The display name of the company this contact is associated with.
string
The primary web domain of the company this contact is associated with.
string
URL to the company’s LinkedIn profile page.
string
The industry classification of the contact’s company.
string
The broader sector of the contact’s company.
string
A short description of the contact’s company.
string
A bucketed headcount range for the contact’s company.
integer
The lower bound of the company’s headcount range.
integer
The upper bound of the company’s headcount range.
string
A bucketed annual revenue range for the contact’s company.
number
The lower bound of the company’s annual revenue range in USD.
number
The upper bound of the company’s annual revenue range in USD.
array
A list of phone numbers associated with the contact’s company.
array
A list of tags applied to the contact’s company account in Knock2.
array
A list of technologies detected in use at the contact’s company.
string
The city where the contact’s company is located.
string
The state or province where the contact’s company is located.
string
The postal or ZIP code for the contact’s company address.
string
The country where the contact’s company is located (ISO 3166-1 alpha-2 code).
string
A human-readable location string for the contact’s company.
string
ISO 8601 date of the company’s most recent funding event.
string
The type of the company’s most recent funding round.
string
The amount raised in the company’s most recent funding round.
string
The lead source of the associated CRM deal, if synced.
string
The name of the associated CRM deal, if synced.
string
The pipeline stage of the associated CRM deal.
number
The monetary value of the associated CRM deal in USD.
string
ISO 8601 timestamp of the expected or actual close date for the associated CRM deal.
string
Email address of the deal owner in your CRM.
string
First name of the deal owner in your CRM.
string
Last name of the deal owner in your CRM.
string
Email address of the company owner in your CRM.
string
First name of the company owner in your CRM.
string
Last name of the company owner in your CRM.
string
The corresponding HubSpot Company record ID, if synced.
string
The corresponding Salesforce Account record ID, if synced.
string
ISO 8601 timestamp of the contact’s most recent visit.
string
The URL path of the most recently visited page on your website.
array
The contact’s most recent page visits (up to 100), newest first. Each entry has
page (string), start_time (ISO 8601), and end_time (ISO 8601, null if the visit is still open).integer
The total cumulative time in seconds this contact has spent on your website.
object
A map of all UTM parameters captured from this contact’s visits.
string
The referrer URL from the contact’s most recent visit.
string
The
utm_source value from the most recent tracked visit.string
The
utm_medium value from the most recent tracked visit.string
The
utm_campaign value from the most recent tracked visit.string
The
utm_term value from the most recent tracked visit.string
The
utm_content value from the most recent tracked visit.string
The ID of the ICP definition used to score this contact.
string
The display name of the ICP definition used to score this contact.
integer
A numeric ICP fit score between
0 and 100. Higher scores indicate a closer match to your configured Ideal Customer Profile.string
A human-readable explanation of why this contact received their ICP score.
string | null
The ID your page passed to
window.knock2.setExternalId("...") on this contact’s browser. null if this contact’s browser never called it. See Pass Your Own IDs.object
Every ID your page passed to
window.knock2.setExternalId({...}) on this contact’s browser, by the names you gave them (newest value per name). A plain setExternalId("...") call is under the key external_id. An empty object if this contact’s browser never called it.string
ISO 8601 timestamp of when this contact was first identified by Knock2.
Error Responses
| HTTP Status | code | Description |
|---|---|---|
401 | unauthorized | Your API key is missing or invalid. |
403 | forbidden | Your API key does not have the contacts:read scope. |
404 | not_found | No contact was found for the given ID — including a malformed (non-UUID) contact_id, which is rejected as not-found rather than triggering a database error. |
422 | validation_error | The request parameters failed validation. |
429 | rate_limit_exceeded | You have exceeded the rate limit. Apply exponential backoff and retry. |
401 Unauthorized
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key.",
"details": null
}
}
404 Not Found
{
"error": {
"code": "not_found",
"message": "No contact found for the provided ID.",
"details": null
}
}
422 Validation Error
{
"error": {
"code": "validation_error",
"message": "Invalid contact_id format.",
"details": null
}
}
429 Rate limit exceeded
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Please slow down and retry with exponential backoff.",
"details": null
}
}