> ## Documentation Index > Fetch the complete documentation index at: https://docs.knock2.ai/llms.txt > Use this file to discover all available pages before exploring further. # GET /v1/contacts — List Identified Contacts > GET /v1/contacts returns a paginated list of identified individual contacts. Filter by email, account_id, filter_set_id, or inline filter JSON. The List Contacts endpoint returns a paginated list of every individual contact Knock2 has identified visiting your website. Each record includes personal details such as name, job title, and email address alongside the company they belong to, their ICP (Ideal Customer Profile) score, and a summary of their most recent visit activity. Use the `account_id` parameter to scope results to contacts from a specific company, the `email` parameter for a direct lookup, or build richer segmentation with `filter_set_id` or inline `filters`. *** ## Endpoint ```text theme={null} GET https://api.knock2.ai/v1/contacts ``` *** ## Required Scope Your API key must have the `contacts:read` scope (or the broader `all:read` scope) to call this endpoint. *** ## Request Parameters The maximum number of contact records to return in a single response. Must be between `1` and `100`. Defaults to `50`. An opaque pagination cursor returned by a previous List Contacts response as `next_cursor`. Omit this parameter on your first request. Pass it on subsequent requests to retrieve the next page of results. A URL-encoded JSON array of filter objects to apply to the results, each with `key`, `keyType`, `condition`, and (usually) `value` fields. Filters are combined with a logical AND. Can be combined with `filter_set_id` — see below. Example (before URL encoding): ```json theme={null} [{"key":"title","keyType":"string_searchable","condition":"contains","value":"Engineer"}] ``` The ID of a saved filter set to apply. Filter sets are created and managed in the Knock2 dashboard or via the Filter Sets API. `filters` and `filter_set_id` are **not** mutually exclusive — when both are provided, the saved filter set's conditions are used as the base and the inline `filters` are appended on top (all conditions must match). Filter results to a single contact by their exact email address (e.g. `jane@acme.com`). Returns at most one record. Use this as a lightweight lookup shortcut instead of constructing a `filters` query. Filter results to contacts associated with a specific account. Pass the Knock2 account ID (e.g. `acc_01HX...`) to scope the list to that company's identified visitors. Read a direct child tenant's contacts 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](/tenants/managing-tenants#reading-a-child-tenants-data). 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`. If you also pass `filter_set_id`, the filter set must belong to the tenant being read. *** ## Example Requests ```bash Basic request theme={null} curl https://api.knock2.ai/v1/contacts \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```bash Lookup by email theme={null} curl "https://api.knock2.ai/v1/contacts?email=jane@acme.com" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```bash Filter by account theme={null} curl "https://api.knock2.ai/v1/contacts?account_id=acc_01HX..." \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```bash With pagination theme={null} curl "https://api.knock2.ai/v1/contacts?limit=25&cursor=eyJpZCI6ImNudF8wMUhYIn0=" \ -H "Authorization: Bearer YOUR_API_KEY" ``` *** ## Response Returns `200 OK` with a paginated list of contact objects. ```json Example response theme={null} { "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"], "company_id": "acc_01HX...", "company_name": "Acme Corp", "company_domain": "acme.com", "icp_scoring_score": 87, "icp_scoring_reason": "Matches target industry and seniority level.", "latest_visit_page": "/docs/api", "latest_visit_datetime": "2024-06-01T14:23:00Z", "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" } ], "created_at": "2024-05-20T11:00:00Z" } ], "has_more": true, "next_cursor": "eyJpZCI6ImNudF8wMUhYIn0=" } ``` ### Response Fields An array of contact objects for the current page. The unique Knock2 identifier for this contact. The contact's first name. The contact's last name. The contact's full display name. The contact's job title (e.g. `"Head of Engineering"`). The contact's primary email address, if identified. The contact's work email address. The contact's personal email address, if available. URL to the contact's LinkedIn profile. The seniority level of the contact's role (e.g. `"Director"`, `"VP"`, `"C-Suite"`, `"Manager"`). A list of functional departments the contact is associated with (e.g. `["Engineering"]`, `["Sales", "Marketing"]`). A list of phone numbers associated with the contact. The city the contact is based in. The state or province the contact is based in. The postal or ZIP code for the contact's address. The country the contact is based in (ISO 3166-1 alpha-2 code, e.g. `"US"`). A human-readable location string combining city, state, and country. How this contact was matched to a website visit (e.g. `"email"`, `"ip"`). `true` if this contact has been marked as qualified based on your configured criteria. `true` if the contact's business email address has been validated as deliverable. ISO 8601 timestamp of when the business email was last validated. ISO 8601 timestamp of when this contact's profile was last enriched. The Knock2 account ID of the company this contact is associated with. The display name of the company this contact is associated with. The primary web domain of the company this contact is associated with. URL to the company's LinkedIn profile page. The industry classification of the contact's company. The broader sector of the contact's company. A short description of the contact's company. A bucketed headcount range for the contact's company. The lower bound of the company's headcount range. The upper bound of the company's headcount range. A bucketed annual revenue range for the contact's company. The lower bound of the company's annual revenue range in USD. The upper bound of the company's annual revenue range in USD. A list of phone numbers associated with the contact's company. A list of tags applied to the contact's company account in Knock2. A list of technologies detected in use at the contact's company. The city where the contact's company is located. The state or province where the contact's company is located. The postal or ZIP code for the contact's company address. The country where the contact's company is located (ISO 3166-1 alpha-2 code). A human-readable location string for the contact's company. ISO 8601 date of the company's most recent funding event. The type of the company's most recent funding round. The amount raised in the company's most recent funding round. The lead source of the associated CRM deal, if synced. The name of the associated CRM deal, if synced. The pipeline stage of the associated CRM deal. The monetary value of the associated CRM deal in USD. ISO 8601 timestamp of the expected or actual close date for the associated CRM deal. Email address of the deal owner in your CRM. First name of the deal owner in your CRM. Last name of the deal owner in your CRM. Email address of the company owner in your CRM. First name of the company owner in your CRM. Last name of the company owner in your CRM. The corresponding HubSpot Company record ID, if synced. The corresponding Salesforce Account record ID, if synced. ISO 8601 timestamp of the contact's most recent visit. The URL path of the most recent page this contact visited on your website. The contact's most recent page visits (up to 20), newest first. Each entry has `page` (string), `start_time` (ISO 8601), and `end_time` (ISO 8601, `null` if the visit is still open). For a contact's complete visit history beyond this cap, use [List Activity](/api-reference/activity/list-activity) with `contact_id`. The total cumulative time in seconds this contact has spent on your website. A map of all UTM parameters captured from this contact's visits. The referrer URL from the contact's most recent visit. The `utm_source` value from the most recent tracked visit. The `utm_medium` value from the most recent tracked visit. The `utm_campaign` value from the most recent tracked visit. The `utm_term` value from the most recent tracked visit. The `utm_content` value from the most recent tracked visit. The ID of the ICP definition used to score this contact. The display name of the ICP definition used to score this contact. A numeric ICP fit score between `0` and `100`. Higher scores indicate a closer match to your Ideal Customer Profile. A human-readable explanation of why this contact received their ICP score. ISO 8601 timestamp of when this contact was first identified by Knock2. `true` if there are additional pages of results after this one. Pass `next_cursor` as the `cursor` parameter in your next request to retrieve them. An opaque string you pass as the `cursor` parameter in your next request to retrieve the next page. `null` when `has_more` is `false` and you have reached the last page. *** ## 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. | | `422` | `invalid_request` | One or more query parameters failed validation. | | `429` | `rate_limit_exceeded` | You have exceeded the rate limit. Apply exponential backoff and retry. | ```json 401 Unauthorized theme={null} { "error": { "code": "unauthorized", "message": "Invalid or missing API key.", "details": null } } ``` ```json 422 Invalid Request theme={null} { "error": { "code": "invalid_request", "message": "Missing required fields: limit", "details": null } } ``` ```json 429 Rate limit exceeded theme={null} { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and retry with exponential backoff.", "details": null } } ```