> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

> Fetch customers in a campaign, optionally filtered by IDs, language, or customer data.

### Headers

**Authorization** `string` *required*

Bearer token for authentication (e.g., `Bearer <your_token>`).

**X-ORG-ID** `string`

Optional. Use this header only when the authenticated user belongs to multiple organizations. It identifies the organization to target for this action.

### Query Parameters

**page** `integer` (default: 1)

The page number for pagination.

### Body Parameters

**campaignId** `string` *required*

The unique identifier of the campaign whose customers will be returned.

**filters** `object`

Optional filters to limit the returned customers. Multiple filters are combined with **AND** logic.

**properties**

**ids** `string[]`

Get specific customers by ID. Use `lead_id` for `lead_generation` organizations and `loan_id` for `debt_collection` organizations. Maximum 50 IDs.

**exclude\_ids** `string[]`

Exclude customers by ID. Use `lead_id` for `lead_generation` organizations and `loan_id` for `debt_collection` organizations.

**phone\_number** `string[]`

Return customers whose phone number matches one of the supplied numbers.

**payment\_status** `string[]`

Return customers whose payment status matches one of the supplied values.

**language** `string[]`

Return customers whose preferred language matches one of the supplied languages (for example, `hindi`).

**custom** `object`

Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings. Use `emi_due_date` for `debt_collection` organizations and `lead_date` for `lead_generation` organizations.

```json Example theme={null}
      {
        "branch": "mumbai",
        "product_type": ["personal_loan", "home_loan"],
        "amount": {"from": 1000, "to": 5000},
        "emi_due_date": "2026-09-14", // for debt_collection organizations
        "lead_date": "2026-08-26" // for lead_generation organizations
      }
```

### Response

**success** `boolean`

Indicates whether the request was successful.

**message** `string`

A descriptive message about the result.

**data** `object`

Customers returned for the campaign.

**properties**

**campaignId** `string`

The campaign ID used for the request.

**campaignName** `string`

The name of the campaign.

**customers** `array`

The customer records matching the supplied filters.

**pagination** `object`

Pagination details for the result set.

**properties**

**page** `integer`

Current page number.

**limit** `integer`

Number of customers returned per page. (Always 10)

**total** `integer`

Total number of matching customers.

**totalPages** `integer`

Total number of pages available.

**hasNext** `boolean`

Whether another page is available.

**hasPrev** `boolean`

Whether a previous page is available.

```json 200 OK theme={null}
{
  "success": true,
  "message": "Customers fetched successfully",
  "data": {
    "campaignId": "lSKmrINyfZEywkpPCaGv",
    "campaignName": "Test api",
    "customers": [
      {
        "loan_id": "LOAN-2026-00001",
        "first_name": "Aarav",
        "last_name": "Sharma",
        "phone_number": "9938177282",
        "loan_amount": "8000",
        "loan_period": "60",
        "emi_amount": "8000",
        "emi_due_date": "2026-02-14",
        "current_emi": "5",
        "payment_status": "received",
        "language": "hindi"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

```json 400 Bad Request theme={null}
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "campaignId is required and must be a string"
  ]
}
```

```json 401 Unauthorized theme={null}
{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header"
}
```

```json 403 Forbidden theme={null}
{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have the required permission to perform this action"
}
```

```json 500 Server Error theme={null}
{
  "success": false,
  "error": "InternalServerError",
  "message": "An unexpected error occurred"
}
```

## Error Codes

| Status | Description |
| - | - |
| `400` | Validation error - `campaignId` is required |
| `401` | Unauthorized - missing or invalid authorization header |
| `403` | Forbidden - insufficient permission to access the campaign customers |
| `500` | Internal server error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.