List ICPs
curl --request GET \
--url https://api.example.com/api/v1/entities/icps \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/icps"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/icps', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/icps",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/icps"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/icps")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/icps")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"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": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
ICPs
List ICPs
Retrieves all Ideal Customer Profiles (ICPs) for the authenticated user
GET
/
api
/
v1
/
entities
/
icps
List ICPs
curl --request GET \
--url https://api.example.com/api/v1/entities/icps \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/icps"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/icps', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/icps",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/icps"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/icps")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/icps")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"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": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
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.array
An array of ICP objects the user has access to.
Show ICP object properties
Show ICP object properties
string
required
Unique UUID identifier for the ICP.
string
required
The name of the ICP.
string | null
required
A description of the ICP. May be
null if no description has been set.string
required
ISO 8601 timestamp of when the ICP was created.
string
required
ISO 8601 timestamp of when the ICP was last updated.
array
required
Array of lead provider search criteria. Each criteria specifies a provider and filters for finding leads.
Show Lead provider criteria object
Show Lead provider criteria object
string
required
The lead provider. Currently supports
"baseProvider".string
The type of search:
"person" or "company". Legacy criteria without this field default to person search.object
required
Provider-specific filter object containing search parameters like job titles, locations, industries, company size, etc.
array
required
Array of custom filter criteria applied after lead provider search.
Show Custom filter types
Show Custom filter types
Website Filter (
type: "website")provider: Provider for website analysis (e.g.,"browserUse")prompt: Prompt for evaluating company websites
type: "webscraping")provider: Scraping provider (e.g.,"firecrawl")extractionPrompt: Prompt for data extractionpageFindingPrompt: Prompt for finding relevant pagesincludeSearchStrings: Array of strings to includeexcludeSearchStrings: Array of strings to exclude
type: "ai")entityType: Entity to evaluate ("company"or"person")prompt: AI evaluation prompt
type: "maxPeoplePerCompany")value: Maximum number of leads per company (default: 1)
type: "maxPercentFromCRM")value: Maximum percentage of leads from CRM (default: 100)
type: "minDaysUntilReuse")value: Minimum days before a lead can be reused (default: 365)
type: "matchFieldWithRegex")field: Field path (e.g.,"firstName","company.headcount")regex: Regex pattern to match
object | null | undefined
CRM integration filters for sourcing leads from connected CRM systems. This field is both optional and nullable.
Show CRM filters object
Show CRM filters object
string
required
CRM provider. Currently supports
"bullhorn".string | null | undefined
Free-text search for occupation/title field (e.g.,
"Head OR Leit* OR Direktor"). This field is both optional and nullable.array
Array of structured filter conditions with
path, mode, value, and exclude properties.string | null | undefined
Legacy query field. Optional and nullable. Retained for backward compatibility.
array
required
Array of Clerk user IDs that have access to this ICP.
number
required
Number of leads to include per generated lead list. Default is 10.
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": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
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. |