Update ICP

curl --request PATCH \
  --url https://api.example.com/api/v1/entities/icps/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": {},
  "userIds": [
    {
      "userIds[]": "<string>"
    }
  ],
  "leadsPerList": 123,
  "activeUntil": {},
  "leadProviderCriteria": [
    {
      "leadProviderCriteria[].provider": "<string>",
      "leadProviderCriteria[].type": "<string>",
      "leadProviderCriteria[].filters": {}
    }
  ],
  "customFilterCriteria": [
    {
      "customFilterCriteria[].type": "<string>"
    }
  ],
  "crmFilters": {
    "crmFilters.provider": "<string>",
    "crmFilters.textSearch": {},
    "crmFilters.query": {},
    "crmFilters.filters": [
      {
        "crmFilters.filters[].path": "<string>",
        "crmFilters.filters[].mode": "<string>",
        "crmFilters.filters[].value": {},
        "crmFilters.filters[].exclude": true
      }
    ]
  }
}
'

{
  "name": "Updated ICP Name",
  "leadsPerList": 50,
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 5
    }
  ]
}

PATCH

api

entities

icps

{id}

Update ICP

curl --request PATCH \
  --url https://api.example.com/api/v1/entities/icps/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": {},
  "userIds": [
    {
      "userIds[]": "<string>"
    }
  ],
  "leadsPerList": 123,
  "activeUntil": {},
  "leadProviderCriteria": [
    {
      "leadProviderCriteria[].provider": "<string>",
      "leadProviderCriteria[].type": "<string>",
      "leadProviderCriteria[].filters": {}
    }
  ],
  "customFilterCriteria": [
    {
      "customFilterCriteria[].type": "<string>"
    }
  ],
  "crmFilters": {
    "crmFilters.provider": "<string>",
    "crmFilters.textSearch": {},
    "crmFilters.query": {},
    "crmFilters.filters": [
      {
        "crmFilters.filters[].path": "<string>",
        "crmFilters.filters[].mode": "<string>",
        "crmFilters.filters[].value": {},
        "crmFilters.filters[].exclude": true
      }
    ]
  }
}
'

{
  "name": "Updated ICP Name",
  "leadsPerList": 50,
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 5
    }
  ]
}

Updates an existing ICP (Ideal Customer Profile) with the provided fields. This endpoint supports partial updates - only include the fields you want to change. Fields not included in the request body will remain unchanged.

Authentication

This endpoint requires authentication. The user must be signed in.

Users can only update ICPs where they are listed in the userIds array, or if they are an admin user. Attempting to update an ICP without proper authorization will result in a 403 Forbidden error.

Request

string

required

The unique identifier (UUID) of the ICP to update.

Request Body

All fields are optional. Only include the fields you want to update.

name

string

The display name of the ICP.

description

string | null

A description of the ICP’s target profile. Set to null to clear.

userIds

array

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

Show Array items

userIds[]

string

A Clerk user ID.

leadsPerList

number

The default number of leads to include when generating lead lists from this ICP.

activeUntil

string | null

ISO 8601 timestamp indicating when the ICP expires. Set to null for indefinite.

leadProviderCriteria

array

Array of search criteria configurations for lead providers.

Show Lead provider criteria object

leadProviderCriteria[].provider

string

required

The lead provider identifier (e.g., "baseProvider").

leadProviderCriteria[].type

string

The search type: "person" or "company".

leadProviderCriteria[].filters

object

required

Provider-specific filter configuration.

customFilterCriteria

array

Array of custom filtering rules applied to leads after retrieval.

Show Custom filter types

customFilterCriteria[].type

string

required

The filter type. One of: "website", "webscraping", "ai", "maxPeoplePerCompany", "maxPercentFromCRM", "minDaysUntilReuse", "matchFieldWithRegex".

Additional fields depend on the filter type:For maxPeoplePerCompany, maxPercentFromCRM, minDaysUntilReuse:

value (number): The numeric threshold value.

For website:

provider (string): The provider (default: "browserUse").
prompt (string): The evaluation prompt.

For webscraping:

provider (string): The provider (default: "firecrawl").
extractionPrompt (string | null): Extraction prompt.
pageFindingPrompt (string | null): Page finding prompt.
includeSearchStrings (array | null): Strings to include.
excludeSearchStrings (array | null): Strings to exclude.

For ai:

entityType (string): "person" or "company".
prompt (string): The AI evaluation prompt.

For matchFieldWithRegex:

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

crmFilters

object | null | undefined

CRM filter configuration. Set to null to remove. This field is both optional and nullable.

Show CRM filters properties

crmFilters.provider

string

required

The CRM provider (currently only "bullhorn").

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

crmFilters.query

string | null | undefined

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

crmFilters.filters

array

Array of structured filter conditions.

Show Filter condition properties

crmFilters.filters[].path

string

required

Field path using dot notation (e.g., "address.zip", "status").

crmFilters.filters[].mode

string

required

Match mode: "equals", "in", or "startsWith".

crmFilters.filters[].value

string | array

required

Value(s) to match. String for equals/startsWith, array for in mode.

crmFilters.filters[].exclude

boolean

If true, exclude contacts matching this condition. Defaults to false.

Response

Returns the complete updated ICP object.

string

required

Unique identifier (UUID) for the ICP.

name

string

required

The display name of the ICP.

description

string | null

required

A description of the ICP’s target profile.

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 (will reflect the update time).

userIds

array

required

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

leadsPerList

number

required

The default number of leads per list.

activeUntil

string | null

required

ISO 8601 timestamp indicating when the ICP expires.

leadProviderCriteria

array

required

Array of search criteria configurations for lead providers.

customFilterCriteria

array

required

Array of custom filtering rules.

crmFilters

object | null | undefined

CRM filter configuration. This field is both optional and nullable.

Response Examples

{
  "name": "Updated ICP Name",
  "leadsPerList": 50,
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 5
    }
  ]
}

Error Codes

Status Code	Error Code	Description
400	`BAD_REQUEST`	Invalid request body. Check the `details` field for specific validation errors.
401	`UNAUTHORIZED`	User is not authenticated. Ensure a valid session exists.
403	`FORBIDDEN`	User does not have access to this ICP.
404	`NOT_FOUND`	No ICP exists with the specified ID.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

​Authentication

​Request

​Request Body

​Response

​Response Examples

​Error Codes

Authentication

Request

Request Body

Response

Response Examples

Error Codes