---
title: "Get customers"
method: GET
path: "/get-customers/{chatbotId}"
tags: ["Chatbot Analytics"]
---

# Get customers

`GET /get-customers/{chatbotId}`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/get-customers/{chatbotId}`
- Auth: HTTP bearer

Get the customers (leads) collected by a chatbot, newest first. Results are paginated.

## Path parameters

- `chatbotId` string, required

## Query parameters

- `startTimestamp` number: Start of the time range (inclusive) for when customers were collected, in milliseconds since the Unix epoch.
- `endTimestamp` number: End of the time range (exclusive), in milliseconds since the Unix epoch.
- `start` number: The start position of the results, used for pagination.
- `size` number: The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results; `0` returns a 400 error.
- `source` string[]: Filter customers by the source they were acquired from. Repeat the parameter to match several sources.
- `leadId` string: Filter by the lead's UUID (`leadId`).
- `psid` string: Filter by the page-scoped user ID (Messenger).
- `ig_username` string: Filter by the Instagram username.
- `username` string: Filter by the Slack or Telegram username.
- `name` string: Filter by the customer name (exact match).
- `email` string: Filter by the customer email address (exact match).
- `phone` string: Filter by the customer phone number (exact match of the stored value).

## Response `200`

Successful response.

- LeadsRes
  - `status` 'success', required
  - `customers` Customer[], required: The customers, newest first.
    - `leadId` string: The unique identifier of the lead (UUID).
    - `name` string: The name provided by the customer.
    - `email` string: The email address provided by the customer.
    - `phone` string: The phone number provided by the customer.
    - `psid` string: The page-scoped user ID of the customer, if the customer is from Messenger.
    - `ig_username` string: The Instagram username of the customer, if the customer is from Instagram.
    - `username` string: Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).
    - `info` string: Additional information stored on the lead.
    - `source` 'widget' | 'iframe' | 'site' | 'api' | 'Whatsapp' | 'WhatsappWebAPI' | 'Messenger' | 'Instagram' | 'Telegram' | 'Line' | 'Slack' | 'Discord' | 'Workflow Studio' | 'cron-trigger': The source the customer was acquired from. Only returned by get-customers.
    - `ipAddress` string: The IP address of the customer. Only returned by get-customers.
    - `userCountry` string: The 2-letter ISO country code of the customer, based on an IP address lookup (`Unknown` when it could not be resolved). Only returned by get-customers.
    - `createdAt` number, required: When the customer's information was submitted, in milliseconds since the Unix epoch.
  - `total` number, required: Total number of matching customers, ignoring pagination.

## Other responses

- `400`: An unexpected error occurred while processing the request; `message` contains the error.
- `401`: Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.
- `403`: The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.
- `429`: The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)