Skip to main content
GET
/
api
/
v1
/
entities
/
icps
/
{id}
Get ICP
curl --request GET \
  --url https://api.example.com/api/v1/entities/icps/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Enterprise Tech Decision Makers",
  "description": "C-level and VP-level technology leaders at enterprise companies",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:22:00.000Z",
  "userIds": ["user_abc123", "user_def456"],
  "leadsPerList": 25,
  "activeUntil": "2024-12-31T23:59:59.000Z",
  "leadProviderCriteria": [
    {
      "provider": "baseProvider",
      "type": "person",
      "filters": {
        "job_titles": ["CTO", "VP Engineering", "Head of Technology"],
        "company_size": ["501-1000", "1001-5000", "5001+"]
      }
    }
  ],
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 3
    },
    {
      "type": "minDaysUntilReuse",
      "value": 180
    }
  ],
  "crmFilters": null
}
Retrieves the full details of an ICP (Ideal Customer Profile) by its unique identifier. ICPs define the criteria used to search for and filter leads from various providers, including lead provider search criteria, custom filtering rules, and CRM filters.

​
Authentication

This endpoint requires authentication. The user must be signed in.
Users can only access ICPs where they are listed in the userIds array, or if they are an admin user. Attempting to access an ICP without proper authorization will result in a 403 Forbidden error.

​
Request

​
id
string
required
The unique identifier (UUID) of the ICP to retrieve.

​
Response

Returns the complete ICP object.
​
id
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. May be null.
​
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.
​
userIds
array
required
Array of Clerk user IDs that have access to this ICP.
​
leadsPerList
number
required
The default number of leads to include when generating lead lists from this ICP. Defaults to 10.
​
activeUntil
string | null
required
ISO 8601 timestamp indicating when the ICP expires. May be null for indefinite ICPs.
​
leadProviderCriteria
array
required
Array of search criteria configurations for lead providers.
​
customFilterCriteria
array
required
Array of custom filtering rules applied to leads after retrieval.
​
crmFilters
object | null | undefined
Optional CRM filter configuration for integrations like Bullhorn. This field is both optional and nullable.

​
Response Examples

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Enterprise Tech Decision Makers",
  "description": "C-level and VP-level technology leaders at enterprise companies",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:22:00.000Z",
  "userIds": ["user_abc123", "user_def456"],
  "leadsPerList": 25,
  "activeUntil": "2024-12-31T23:59:59.000Z",
  "leadProviderCriteria": [
    {
      "provider": "baseProvider",
      "type": "person",
      "filters": {
        "job_titles": ["CTO", "VP Engineering", "Head of Technology"],
        "company_size": ["501-1000", "1001-5000", "5001+"]
      }
    }
  ],
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 3
    },
    {
      "type": "minDaysUntilReuse",
      "value": 180
    }
  ],
  "crmFilters": null
}

​
Error Codes

Status CodeError CodeDescription
401UNAUTHORIZEDUser is not authenticated. Ensure a valid session exists.
403FORBIDDENUser does not have access to this ICP.
404NOT_FOUNDNo ICP exists with the specified ID.
500INTERNAL_ERRORAn unexpected server error occurred.