List ICPs

curl --request GET \
  --url https://api.example.com/api/v1/entities/icps \
  --header 'Authorization: Bearer <token>'

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Enterprise Tech Buyers",
    "description": "IT decision makers at large enterprises in DACH region",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "IT Director"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 500,
              "max": 10000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      },
      {
        "type": "minDaysUntilReuse",
        "value": 180
      }
    ],
    "crmFilters": null,
    "userIds": ["user_abc123", "user_xyz789"],
    "leadsPerList": 25,
    "activeUntil": "2024-12-31T23:59:59.000Z"
  },
  {
    "id": "660e9500-f39c-52e5-b827-557766551111",
    "name": "SMB Marketing Leaders",
    "description": null,
    "createdAt": "2024-02-01T09:00:00.000Z",
    "updatedAt": "2024-02-01T09:00:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["Marketing Director", "CMO", "Head of Marketing"],
          "company": {
            "employee_size": {
              "min": 50,
              "max": 200
            }
          }
        }
      }
    ],
    "customFilterCriteria": [],
    "crmFilters": {
      "provider": "bullhorn",
      "textSearch": "Marketing*",
      "filters": []
    },
    "userIds": ["user_abc123"],
    "leadsPerList": 10,
    "activeUntil": null
  }
]

GET

api

entities

icps

List ICPs

curl --request GET \
  --url https://api.example.com/api/v1/entities/icps \
  --header 'Authorization: Bearer <token>'

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Enterprise Tech Buyers",
    "description": "IT decision makers at large enterprises in DACH region",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "IT Director"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 500,
              "max": 10000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      },
      {
        "type": "minDaysUntilReuse",
        "value": 180
      }
    ],
    "crmFilters": null,
    "userIds": ["user_abc123", "user_xyz789"],
    "leadsPerList": 25,
    "activeUntil": "2024-12-31T23:59:59.000Z"
  },
  {
    "id": "660e9500-f39c-52e5-b827-557766551111",
    "name": "SMB Marketing Leaders",
    "description": null,
    "createdAt": "2024-02-01T09:00:00.000Z",
    "updatedAt": "2024-02-01T09:00:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["Marketing Director", "CMO", "Head of Marketing"],
          "company": {
            "employee_size": {
              "min": 50,
              "max": 200
            }
          }
        }
      }
    ],
    "customFilterCriteria": [],
    "crmFilters": {
      "provider": "bullhorn",
      "textSearch": "Marketing*",
      "filters": []
    },
    "userIds": ["user_abc123"],
    "leadsPerList": 10,
    "activeUntil": null
  }
]

Retrieves a list of all ICPs (Ideal Customer Profiles) that the currently authenticated user has access to. ICPs define the criteria for targeting leads, including lead provider search filters, custom filtering criteria, and CRM integration settings.

Authentication

This endpoint requires authentication. The user must be signed in to access their ICPs.

Only ICPs where the authenticated user is listed in the userIds array are returned. Users cannot access ICPs they don’t have permission to view.

Request

This endpoint does not require any query parameters or request body.

Response

Returns an array of ICP objects.

icps

array

An array of ICP objects the user has access to.

Show ICP object properties

string

required

Unique UUID identifier for the ICP.

name

string

required

The name of the ICP.

description

string | null

required

A description of the ICP. May be null if no description has been set.

createdAt

string

required

ISO 8601 timestamp of when the ICP was created.

updatedAt

string

required

ISO 8601 timestamp of when the ICP was last updated.

leadProviderCriteria

array

required

Array of lead provider search criteria. Each criteria specifies a provider and filters for finding leads.

Show Lead provider criteria object

provider

string

required

The lead provider. Currently supports "baseProvider".

type

string

The type of search: "person" or "company". Legacy criteria without this field default to person search.

filters

object

required

Provider-specific filter object containing search parameters like job titles, locations, industries, company size, etc.

customFilterCriteria

array

required

Array of custom filter criteria applied after lead provider search.

Show Custom filter types

Website Filter (type: "website")

provider: Provider for website analysis (e.g., "browserUse")
prompt: Prompt for evaluating company websites

Web Scraping Filter (type: "webscraping")

provider: Scraping provider (e.g., "firecrawl")
extractionPrompt: Prompt for data extraction
pageFindingPrompt: Prompt for finding relevant pages
includeSearchStrings: Array of strings to include
excludeSearchStrings: Array of strings to exclude

AI Filter (type: "ai")

entityType: Entity to evaluate ("company" or "person")
prompt: AI evaluation prompt

Max People Per Company (type: "maxPeoplePerCompany")

value: Maximum number of leads per company (default: 1)

Max Percent From CRM (type: "maxPercentFromCRM")

value: Maximum percentage of leads from CRM (default: 100)

Min Days Until Reuse (type: "minDaysUntilReuse")

value: Minimum days before a lead can be reused (default: 365)

Match Field With Regex (type: "matchFieldWithRegex")

field: Field path (e.g., "firstName", "company.headcount")
regex: Regex pattern to match

crmFilters

object | null | undefined

CRM integration filters for sourcing leads from connected CRM systems. This field is both optional and nullable.

Show CRM filters object

provider

string

required

CRM provider. Currently supports "bullhorn".

textSearch

string | null | undefined

Free-text search for occupation/title field (e.g., "Head OR Leit* OR Direktor"). This field is both optional and nullable.

filters

array

Array of structured filter conditions with path, mode, value, and exclude properties.

query

string | null | undefined

Legacy query field. Optional and nullable. Retained for backward compatibility.

userIds

array

required

Array of Clerk user IDs that have access to this ICP.

leadsPerList

number

required

Number of leads to include per generated lead list. Default is 10.

activeUntil

string | null

required

ISO 8601 timestamp indicating when the ICP expires. null means no expiration.

Response Examples

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Enterprise Tech Buyers",
    "description": "IT decision makers at large enterprises in DACH region",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "IT Director"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 500,
              "max": 10000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      },
      {
        "type": "minDaysUntilReuse",
        "value": 180
      }
    ],
    "crmFilters": null,
    "userIds": ["user_abc123", "user_xyz789"],
    "leadsPerList": 25,
    "activeUntil": "2024-12-31T23:59:59.000Z"
  },
  {
    "id": "660e9500-f39c-52e5-b827-557766551111",
    "name": "SMB Marketing Leaders",
    "description": null,
    "createdAt": "2024-02-01T09:00:00.000Z",
    "updatedAt": "2024-02-01T09:00:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["Marketing Director", "CMO", "Head of Marketing"],
          "company": {
            "employee_size": {
              "min": 50,
              "max": 200
            }
          }
        }
      }
    ],
    "customFilterCriteria": [],
    "crmFilters": {
      "provider": "bullhorn",
      "textSearch": "Marketing*",
      "filters": []
    },
    "userIds": ["user_abc123"],
    "leadsPerList": 10,
    "activeUntil": null
  }
]

Error Codes

Status Code	Error Code	Description
401	`UNAUTHORIZED`	User is not authenticated. Ensure a valid session exists.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

​Authentication

​Request

​Response

​Response Examples

​Error Codes

Authentication

Request

Response

Response Examples

Error Codes