curl -G "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/customer-profiles" \
-H "Authorization: Bearer bot_live_YOUR_KEY" \
--data-urlencode "skip=0" \
--data-urlencode "limit=20" \
--data-urlencode "search=alex" \
--data-urlencode "sort_field=last_interaction_at" \
--data-urlencode "sort_order=-1"
const params = new URLSearchParams({
skip: "0",
limit: "20",
search: "alex",
sort_field: "last_interaction_at",
sort_order: "-1",
});
const response = await fetch(
`https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/customer-profiles?${params}`,
{ headers: { "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}` } }
);
import os
import requests
response = requests.get(
f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/customer-profiles",
headers={"Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}"},
params={
"skip": 0,
"limit": 20,
"search": "alex",
"sort_field": "last_interaction_at",
"sort_order": -1,
},
)
{
"status": "success",
"message": "Customer profiles retrieved successfully",
"data": {
"items": [
{
"_id": "665f40000000000000000001",
"name": "Alex Rivera",
"email": null,
"phone_number": "+14155552671",
"display_id": "CUS-1042",
"phone_numbers": [
{
"value": "+14155552671",
"normalized": "+14155552671",
"source": "voice"
}
],
"emails": [],
"channel_identities": [
{
"channel_type": "web",
"identity_key": "anon_abc",
"first_seen_at": "2026-07-01T10:00:00Z",
"last_seen_at": "2026-07-21T15:04:00Z"
}
],
"properties": { "plan": "pro" },
"conversation_count": 5,
"call_count": 2,
"chat_count": 3,
"last_interaction_at": "2026-07-21T15:04:00Z"
}
],
"pagination": {
"total": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
},
"status_code": 200
}
Customer Profiles
List customer profiles
Paginated list of unified customer profiles for a project
GET
/
organizations
/
{organization_id}
/
projects
/
{project_id}
/
customer-profiles
curl -G "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/customer-profiles" \
-H "Authorization: Bearer bot_live_YOUR_KEY" \
--data-urlencode "skip=0" \
--data-urlencode "limit=20" \
--data-urlencode "search=alex" \
--data-urlencode "sort_field=last_interaction_at" \
--data-urlencode "sort_order=-1"
const params = new URLSearchParams({
skip: "0",
limit: "20",
search: "alex",
sort_field: "last_interaction_at",
sort_order: "-1",
});
const response = await fetch(
`https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/customer-profiles?${params}`,
{ headers: { "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}` } }
);
import os
import requests
response = requests.get(
f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/customer-profiles",
headers={"Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}"},
params={
"skip": 0,
"limit": 20,
"search": "alex",
"sort_field": "last_interaction_at",
"sort_order": -1,
},
)
{
"status": "success",
"message": "Customer profiles retrieved successfully",
"data": {
"items": [
{
"_id": "665f40000000000000000001",
"name": "Alex Rivera",
"email": null,
"phone_number": "+14155552671",
"display_id": "CUS-1042",
"phone_numbers": [
{
"value": "+14155552671",
"normalized": "+14155552671",
"source": "voice"
}
],
"emails": [],
"channel_identities": [
{
"channel_type": "web",
"identity_key": "anon_abc",
"first_seen_at": "2026-07-01T10:00:00Z",
"last_seen_at": "2026-07-21T15:04:00Z"
}
],
"properties": { "plan": "pro" },
"conversation_count": 5,
"call_count": 2,
"chat_count": 3,
"last_interaction_at": "2026-07-21T15:04:00Z"
}
],
"pagination": {
"total": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
},
"status_code": 200
}
Returns unified customer profiles (one row per person) with conversation stats.
Authentication
string
required
Project API key for this organization and project. Format:
bot_live_…Path parameters
string
required
Organization ID. Must match the API key.
string
required
Project ID. Must match the API key.
Query parameters
integer
default:"0"
Number of records to skip.
integer
default:"20"
Page size. Range:
1–1000.string
Search by name, email, phone, or display id.
string
Filter by
channel_type identity.string
default:"last_interaction_at"
Field to sort by.
integer
default:"-1"
1 ascending, -1 descending.datetime
Filter by interaction/activity from this datetime.
datetime
Filter by interaction/activity until this datetime.
Response
array
required
Customer profile objects.
string
Display name.
string | null
Canonical primary email. Additional addresses are listed in
emails.string | null
Canonical primary phone number. Additional numbers are listed in
phone_numbers.string
Human-readable customer id.
array
required
Phone contact methods.
array
required
Email contact methods.
array
required
Channel identities (
channel_type, identity_key, first/last seen).object
required
Custom property bag.
integer
required
Total conversations.
integer
required
Voice call count.
integer
required
Chat conversation count.
string
Most recent interaction timestamp.
object
required
Pagination metadata.
Errors
Unauthorized
Missing, invalid, or revoked API key.
Forbidden
API key is not authorized for this organization or project.
curl -G "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/customer-profiles" \
-H "Authorization: Bearer bot_live_YOUR_KEY" \
--data-urlencode "skip=0" \
--data-urlencode "limit=20" \
--data-urlencode "search=alex" \
--data-urlencode "sort_field=last_interaction_at" \
--data-urlencode "sort_order=-1"
const params = new URLSearchParams({
skip: "0",
limit: "20",
search: "alex",
sort_field: "last_interaction_at",
sort_order: "-1",
});
const response = await fetch(
`https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/customer-profiles?${params}`,
{ headers: { "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}` } }
);
import os
import requests
response = requests.get(
f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/customer-profiles",
headers={"Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}"},
params={
"skip": 0,
"limit": 20,
"search": "alex",
"sort_field": "last_interaction_at",
"sort_order": -1,
},
)
{
"status": "success",
"message": "Customer profiles retrieved successfully",
"data": {
"items": [
{
"_id": "665f40000000000000000001",
"name": "Alex Rivera",
"email": null,
"phone_number": "+14155552671",
"display_id": "CUS-1042",
"phone_numbers": [
{
"value": "+14155552671",
"normalized": "+14155552671",
"source": "voice"
}
],
"emails": [],
"channel_identities": [
{
"channel_type": "web",
"identity_key": "anon_abc",
"first_seen_at": "2026-07-01T10:00:00Z",
"last_seen_at": "2026-07-21T15:04:00Z"
}
],
"properties": { "plan": "pro" },
"conversation_count": 5,
"call_count": 2,
"chat_count": 3,
"last_interaction_at": "2026-07-21T15:04:00Z"
}
],
"pagination": {
"total": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
},
"status_code": 200
}