GET /v1/accounts — List Identified Accounts

The List Accounts endpoint returns a paginated list of every company account Knock2 has identified visiting your website. Each record includes firmographic data — company name, domain, industry, employee count, estimated revenue — alongside behavioral data such as the latest visited page and total browsing time. You can narrow results to a specific company by passing a domain parameter, apply a pre-built filter set with filter_set_id, or construct ad-hoc filter logic with the filters parameter.

Endpoint

GET https://api.knock2.ai/v1/accounts

Required Scope

Your API key must have the accounts:read scope (or the broader all:read scope) to call this endpoint.

Request Parameters

integer

default:50

The maximum number of account records to return in a single response. Must be between 1 and 100. Defaults to 50.

string

An opaque pagination cursor returned by a previous List Accounts response as next_cursor. Omit this parameter on your first request. Pass it on subsequent requests to retrieve the next page of results.

string

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):

[{"key":"industry","keyType":"string_arr","condition":"is_one_of","value":["Software"]}]

string

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).

string

Filter results to a single company by their exact domain (e.g. acme.com). Returns at most one record. Use this as a lightweight lookup shortcut instead of constructing a filters query.

string

Read a direct child tenant’s accounts 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. If you also pass filter_set_id, the filter set must belong to the tenant being read.

Example Requests

curl https://api.knock2.ai/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.knock2.ai/v1/accounts?domain=acme.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.knock2.ai/v1/accounts?limit=25&cursor=eyJpZCI6ImFjY18wMUhYIn0=" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.knock2.ai/v1/accounts?filters=%5B%7B%22key%22%3A%22industry%22%2C%22keyType%22%3A%22string_arr%22%2C%22condition%22%3A%22is_one_of%22%2C%22value%22%3A%5B%22Software%22%5D%7D%5D" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns 200 OK with a paginated list of account objects.

Example response

{
  "data": [
    {
      "id": "acc_01HX...",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo_url": "https://logo.clearbit.com/acme.com",
      "linkedin_url": "https://www.linkedin.com/company/acme-corp",
      "industry": "Software",
      "sector": "Technology",
      "description": "Acme Corp builds enterprise workflow automation tools.",
      "estimated_employee_count": "51-200",
      "estimated_annual_revenue": "10M-50M",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_country": "US",
      "location": "San Francisco, CA, US",
      "latest_visit_page": "/pricing",
      "latest_visit_datetime": "2024-06-01T14:23:00Z",
      "page_visits": [
        {
          "page": "/pricing",
          "start_time": "2024-06-01T14:20:00Z",
          "end_time": "2024-06-01T14:23:45Z"
        }
      ],
      "total_browsing_time_seconds": 342,
      "is_from_enrichment": false,
      "created_at": "2024-05-15T09:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImFjY18wMUhYIn0="
}

Response Fields

array

required

An array of account objects for the current page.

Show Account object fields

string

The unique Knock2 identifier for this account.

string

The company’s display name (e.g. "Acme Corp").

string

The company’s primary web domain (e.g. "acme.com").

string

URL to the company’s logo image, if available.

string

URL to the company’s LinkedIn profile page.

string

The company’s industry classification (e.g. "Software", "Financial Services").

string

The broader sector the company belongs to (e.g. "Technology", "Healthcare").

string

A short company description sourced from enrichment data.

string

A bucketed range representing the company’s headcount (e.g. "51-200", "201-500").

string

A bucketed range representing the company’s estimated annual revenue (e.g. "10M-50M", "50M-200M").

array

A list of phone numbers associated with the company.

array

A list of tags applied to this account in Knock2.

array

A list of technologies detected in use at this company (e.g. "Salesforce", "HubSpot").

string

The city where the company is located.

string

The state or province where the company is located.

string

The postal or ZIP code for the company’s address.

string

The country where the company is located (ISO 3166-1 alpha-2 code, e.g. "US").

string

A human-readable location string combining city, state, and country.

string

ISO 8601 date of the company’s most recent funding event, if available.

string

The type of the most recent funding round (e.g. "Series A", "Seed").

string

The amount raised in the 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 (e.g. "Proposal", "Closed Won").

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 account’s most recent visit.

string

The URL path of the most recent page this account visited on your website (e.g. "/pricing").

array

The account’s most recent page visits (up to 20 per account in the list response), newest first. Each entry has page (string), start_time (ISO 8601), and end_time (ISO 8601, null if the visit is still open). Call Get Account for the full (up to 100) history.

integer

The total cumulative time in seconds this account has spent on your website across all sessions.

object

A map of all UTM parameters captured from this account’s visits.

string

The referrer URL from the account’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.

boolean

true if this account record was created via enrichment rather than a live website visit.

string

ISO 8601 timestamp of when this account was first identified by Knock2.

boolean

required

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.

string | null

required

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 `accounts: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.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": null
  }
}

422 Invalid Request

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required fields: limit",
    "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
  }
}

Overview

Accounts

Contacts

Activity & Scores

Filter Sets

Webhooks

Enrichment & Auth

Tenants & Script

GET /v1/accounts — List Identified Accounts

Endpoint

Required Scope

Request Parameters

Example Requests

Response

Response Fields

Error Responses

​Endpoint

​Required Scope

​Request Parameters

​Example Requests

​Response

​Response Fields

​Error Responses

Endpoint

Required Scope

Request Parameters

Example Requests

Response

Response Fields

Error Responses