# Get customers

`GET https://api.chat-data.com/api/v2/get-customers/{chatbotId}`

Canonical: https://www.chat-data.com/api-reference/get-customers

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| chatbotId | path | string | yes | The unique identifier allocated to the chatbot. |
| startTimestamp | query | number | no | Start of the time range (inclusive) for when customers were collected, in milliseconds since the Unix epoch. |
| endTimestamp | query | number | no | End of the time range (exclusive), in milliseconds since the Unix epoch. |
| start | query | number | no | The start position of the results, used for pagination. |
| size | query | number | no | 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 | query | array of string | no | Filter customers by the source they were acquired from. Repeat the parameter to match several sources. |
| leadId | query | string | no | Filter by the lead's UUID (`leadId`). |
| psid | query | string | no | Filter by the page-scoped user ID (Messenger). |
| ig_username | query | string | no | Filter by the Instagram username. |
| username | query | string | no | Filter by the Slack or Telegram username. |
| name | query | string | no | Filter by the customer name (exact match). |
| email | query | string | no | Filter by the customer email address (exact match). |
| phone | query | string | no | Filter by the customer phone number (exact match of the stored value). |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/get-customers/6650f1c2a9e4b83d2c7a1f05' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY"
```

## Example response (200)

```json
{
  "status": "success",
  "customers": [
    {
      "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",
      "name": "Jane Doe",
      "email": "jane@chat-data.com",
      "source": "widget",
      "phone": "+14155550123",
      "ipAddress": "203.0.113.42",
      "userCountry": "US",
      "createdAt": 1791970200000
    }
  ],
  "total": 10
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 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. |