Get ICP
curl --request GET \
--url https://api.example.com/api/v1/entities/icps/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/icps/{id}"
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/{id}', 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/{id}",
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/{id}"
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/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/icps/{id}")
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 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": {
"code": "FORBIDDEN",
"message": "You do not have access to this ICP"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "ICP not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
ICPs
Get ICP
Retrieves a single ICP (Ideal Customer Profile) by its ID
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>'import requests
url = "https://api.example.com/api/v1/entities/icps/{id}"
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/{id}', 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/{id}",
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/{id}"
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/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/icps/{id}")
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 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": {
"code": "FORBIDDEN",
"message": "You do not have access to this ICP"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "ICP not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
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
string
required
The unique identifier (UUID) of the ICP to retrieve.
Response
Returns the complete ICP object.string
required
Unique identifier (UUID) for the ICP.
string
required
The display name of the ICP.
string | null
required
A description of the ICP’s target profile. May be
null.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 Clerk user IDs that have access to this ICP.
number
required
The default number of leads to include when generating lead lists from this
ICP. Defaults to 10.
string | null
required
ISO 8601 timestamp indicating when the ICP expires. May be
null for
indefinite ICPs.array
required
Array of search criteria configurations for lead providers.
array
required
Array of custom filtering rules applied to leads after retrieval.
Show Custom filter types
Show Custom filter types
string
required
The filter type. One of:
"website", "webscraping", "ai", "maxPeoplePerCompany", "maxPercentFromCRM", "minDaysUntilReuse", "matchFieldWithRegex".object | null | undefined
Optional CRM filter configuration for integrations like Bullhorn. This field is both optional and nullable.
Show CRM filters properties
Show CRM filters properties
string
required
The CRM provider (currently only
"bullhorn").string | null | undefined
Free-text search for occupation/title field. 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.
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": {
"code": "FORBIDDEN",
"message": "You do not have access to this ICP"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "ICP not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 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. |