> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

> Retrieve a paginated list of all customers registered under your company.

## Overview

`GET /customers` returns a paginated list of customers registered under your company. Use it to render a back-office customer list, search, or to reconcile your local cache against Cartevo.

## When to use it

* Render a "all customers" view in your dashboard.
* Find a customer by name/email when their ID is not at hand.
* Reconcile your local customer database against Cartevo's source of truth.

## Prerequisites

* Authenticated as a company user.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

### Query parameters

| Name    | Type    | Default | Description                                                                                    |
| ------- | ------- | ------- | ---------------------------------------------------------------------------------------------- |
| `page`  | integer | `1`     | 1-indexed page number.                                                                         |
| `limit` | integer | `10`    | Items per page. Max recommended: `100`.                                                        |
| `sync`  | boolean | `false` | If `true`, force a re-sync from the upstream provider before returning. Slower; use sparingly. |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "10 items retrieved successfully",
  "data": [
    {
      "id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "country": "Cameroon",
      "phone_country_code": "+237",
      "phone_number": "600000000",
      "is_active": true,
      "created_at": "2026-05-09T10:15:00.000Z",
      "updated_at": "2026-05-09T10:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 137,
    "totalPages": 14
  }
}
```

For the per-customer field reference, see [`GET /customers/{id}`](/api-reference/endpoint/get-customer-by-id).

### Error responses

| Status | Trigger                          |
| ------ | -------------------------------- |
| `401`  | Missing or expired Bearer token. |

## Code examples

```bash cURL theme={null}
curl -G https://api.cartevo.co/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50"
```

```js Node.js (axios) theme={null}
const { data } = await axios.get("https://api.cartevo.co/api/v1/customers", {
  headers: { Authorization: `Bearer ${token}` },
  params: { page: 1, limit: 50 },
});
console.log(`${data.meta.total} customers total`);
```

## Related

* [`POST /customers`](/api-reference/endpoint/post-customers) — register a new customer.
* [`GET /customers/{id}`](/api-reference/endpoint/get-customer-by-id) — full customer detail.


## OpenAPI

````yaml GET /customers
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      summary: List customers
      description: Retrieves a list of all customers for the company.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: A list of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponse'
components:
  schemas:
    ListCustomersResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CustomerDetails'
            pagination:
              $ref: '#/components/schemas/Pagination'
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Data retrieved successfully
    CustomerDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 4d4dad81-7899-4612-a9f6-133ce56a4507
        email:
          type: string
          format: email
          example: customer@example.com
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        is_active:
          type: boolean
          example: true
        country:
          type: string
          example: Cameroon
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 15
        totalPages:
          type: integer
          example: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````