Skip to main content
POST
/
api
/
v1
/
entities
/
icps
Create ICP
curl --request POST \
  --url https://api.example.com/api/v1/entities/icps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": {},
  "leadProviderCriteria": [
    {
      "provider": "<string>",
      "type": "<string>",
      "filters": {}
    }
  ],
  "customFilterCriteria": [
    {}
  ],
  "crmFilters": {
    "provider": "<string>",
    "textSearch": {},
    "query": {},
    "filters": [
      {
        "path": "<string>",
        "mode": "<string>",
        "value": {},
        "exclude": true
      }
    ]
  },
  "userIds": [
    {}
  ],
  "leadsPerList": 123,
  "activeUntil": {}
}
'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "DACH Tech Leaders",
  "description": "Technology leaders in German-speaking regions",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "leadProviderCriteria": [
    {
      "provider": "baseProvider",
      "type": "person",
      "filters": {
        "job_title": ["CTO", "VP Engineering", "Head of Technology"],
        "location": {
          "country": ["Germany", "Austria", "Switzerland"]
        },
        "company": {
          "employee_size": {
            "min": 100,
            "max": 5000
          }
        }
      }
    }
  ],
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 2
    }
  ],
  "crmFilters": null,
  "userIds": ["user_abc123"],
  "leadsPerList": 20,
  "activeUntil": null
}
Creates a new ICP (Ideal Customer Profile) with the specified targeting criteria. The authenticated user is automatically added to the ICP’s userIds array, granting them access to the newly created ICP.

​
Authentication

This endpoint requires authentication. The user must be signed in to create an ICP.
The creating user is automatically added to the userIds array even if not explicitly included in the request body.

​
Request

​
name
string
required
The name of the ICP. Should be descriptive of the target audience.
​
description
string | null
An optional description providing more context about the ICP’s purpose and target criteria.
​
leadProviderCriteria
array
required
Array of lead provider search criteria. At least one criteria should be provided to enable lead sourcing.
​
customFilterCriteria
array
required
Array of custom filters to apply after lead provider search. Can be empty array [] if no custom filters are needed.
​
crmFilters
object | null | undefined
Optional CRM integration filters for sourcing leads from connected CRM systems. This field is both optional and nullable.
​
userIds
array
required
Array of Clerk user IDs that should have access to this ICP. The creating user is automatically included.
​
leadsPerList
number
default:10
Number of leads to include per generated lead list.
​
activeUntil
string | null
ISO 8601 timestamp indicating when the ICP should expire. Set to null for no expiration.

​
Response

Returns the created ICP object.
​
id
string
required
The generated UUID for the new ICP.
​
name
string
required
The name of the ICP.
​
description
string | null
required
The description of the ICP.
​
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 (same as createdAt for new ICPs).
​
leadProviderCriteria
array
required
The lead provider search criteria as provided in the request.
​
customFilterCriteria
array
required
The custom filter criteria as provided in the request.
​
crmFilters
object | null | undefined
The CRM filters as provided in the request. This field is both optional and nullable.
​
userIds
array
required
Array of user IDs with access, including the creating user.
​
leadsPerList
number
required
Number of leads per list.
​
activeUntil
string | null
required
Expiration timestamp or null.

​
Request Examples

{
  "name": "DACH Tech Leaders",
  "description": "Technology leaders in German-speaking regions",
  "leadProviderCriteria": [
    {
      "provider": "baseProvider",
      "type": "person",
      "filters": {
        "job_title": ["CTO", "VP Engineering", "Head of Technology"],
        "location": {
          "country": ["Germany", "Austria", "Switzerland"]
        },
        "company": {
          "employee_size": {
            "min": 100,
            "max": 5000
          }
        }
      }
    }
  ],
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 2
    }
  ],
  "crmFilters": null,
  "userIds": [],
  "leadsPerList": 20,
  "activeUntil": null
}

​
Response Examples

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "DACH Tech Leaders",
  "description": "Technology leaders in German-speaking regions",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "leadProviderCriteria": [
    {
      "provider": "baseProvider",
      "type": "person",
      "filters": {
        "job_title": ["CTO", "VP Engineering", "Head of Technology"],
        "location": {
          "country": ["Germany", "Austria", "Switzerland"]
        },
        "company": {
          "employee_size": {
            "min": 100,
            "max": 5000
          }
        }
      }
    }
  ],
  "customFilterCriteria": [
    {
      "type": "maxPeoplePerCompany",
      "value": 2
    }
  ],
  "crmFilters": null,
  "userIds": ["user_abc123"],
  "leadsPerList": 20,
  "activeUntil": null
}

​
Error Codes

Status CodeError CodeDescription
400BAD_REQUESTInvalid request body. Check the details field for specific validation errors.
401UNAUTHORIZEDUser is not authenticated. Ensure a valid session exists.
500INTERNAL_ERRORAn unexpected server error occurred.