List customer profiles

Paginated list of unified customer profiles for a project

GET /organizations/{organization_id}/projects/{project_id}/customer-profiles

cURL

curl -G "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/customer-profiles" \
  -H "X-API-Key: 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: { "X-API-Key": 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={"X-API-Key": os.environ["BOTCADENCE_API_KEY"]},
    params={
        "skip": 0,
        "limit": 20,
        "search": "alex",
        "sort_field": "last_interaction_at",
        "sort_order": -1,
    },
)

200

{
  "status": "success",
  "message": "Customer profiles retrieved successfully",
  "data": {
    "items": [
      {
        "_id": "665f40000000000000000001",
        "name": "Alex Rivera",
        "display_id": "CUS-1042",
        "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

X-API-Key · string · required

Project API key for this organization and project. Format: bot_live_…

Path parameters

organization_id · string · required

Organization ID. Must match the API key.

project_id · string · required

Project ID. Must match the API key.

Query parameters

skip · integer · default: "0"

Number of records to skip.

limit · integer · default: "20"

Page size. Range: 1–1000.

search · string

Search by name, email, phone, or display id.

channel · string

Filter by channel_type identity.

sort_field · string · default: "last_interaction_at"

Field to sort by.

sort_order · integer · default: "-1"

1 ascending, -1 descending.

date_from · datetime

Filter by interaction/activity from this datetime.

date_to · datetime

Filter by interaction/activity until this datetime.

Response

items · array · required

Customer profile objects with phones, emails, channel identities, properties, and counts.

pagination · object · required

Pagination metadata.

Errors

401 · Unauthorized

Missing, invalid, or revoked API key.

403 · Forbidden

API key is not authorized for this organization or project.

cURL

curl -G "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/customer-profiles" \
  -H "X-API-Key: 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: { "X-API-Key": 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={"X-API-Key": os.environ["BOTCADENCE_API_KEY"]},
    params={
        "skip": 0,
        "limit": 20,
        "search": "alex",
        "sort_field": "last_interaction_at",
        "sort_order": -1,
    },
)

200

{
  "status": "success",
  "message": "Customer profiles retrieved successfully",
  "data": {
    "items": [
      {
        "_id": "665f40000000000000000001",
        "name": "Alex Rivera",
        "display_id": "CUS-1042",
        "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
}