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

# List Customers

> Lists your organization's customers.

<Prompt description="List Customers" actions={["cursor"]}>
  Add the Zapyd "List Customers" call (`GET /cms/api/v1/customer/list`) to my backend. Lists your organization's customers.

  * Sandbox: `GET https://sandbox.zapyd.com/cms/api/v1/customer/list`
  * Production: `GET https://api.zapyd.com/cms/api/v1/customer/list`

  Query parameters:

  * `search` (string, optional): Search by name, email, phone, client\_reference\_id or customer id (min 3 characters).
  * `country` (string, optional): Filter by ISO alpha-3 country code.
  * `customer_status` (string, optional): Filter by customer status.
  * `customer_type` (string, optional): Filter by customer type. One of: `INDIVIDUAL`, `BUSINESS`, `UBO`.
  * `start_date` (string, date, optional): Created on or after (YYYY-MM-DD). Applied only together with end\_date.
  * `end_date` (string, date, optional): Created on or before (YYYY-MM-DD). Applied only together with start\_date.
  * `order_by` (string, optional): Sort field; prefix with - for descending.
  * `page` (integer, optional): Page number.
  * `per_page` (integer, optional): Results per page (10–100).

  Success: HTTP 200, `{status: true, message, data}`. `data`: `count`, `next`, `previous`, `results`.
  Errors (`{status: false, message, err_code, errors}`):

  * 500 `Internal Server Error`
    Every endpoint can also return 401 `AUTH_*` (signature, timestamp or key: fix, don't retry), and 429 or 5xx (retry with backoff).

  Rules:

  * Paginated: `data` has `count`, `next`, `previous` and `results`. `start_date` and `end_date` apply only together.
  * Use `search` (3+ characters) to find a customer by `client_reference_id`, name, email or phone.

  Signing (every request):

  * Headers: `X-API-KEY`, `X-TIMESTAMP` (Unix seconds, within 300 s of server time; generate per request) and `X-SIGNATURE`.
  * `X-SIGNATURE` = Base64(HMAC-SHA256(key = API secret, message = apiKey + "|" + timestamp + "|" + canonicalBody)). Base64 of the raw digest, not hex.
  * canonicalBody: the JSON body with keys sorted at every nesting level, no whitespace (separators `,` and `:`), and every non-ASCII character escaped as lowercase `\uXXXX` (Python `json.dumps(body, sort_keys=True, separators=(",", ":"))`). Requests with no body (GET, DELETE) sign `{}`. Query parameters are not signed.
  * Send the exact canonicalBody string you signed as the request body, with `Content-Type: application/json`.
  * Test vector: key `3f1b2c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d`, secret `test-secret-do-not-use`, timestamp `1735689600`. Signing `{}` gives `6sCtVSRQjU9+2/af8gdwUAvY1l6Ii6ENcbRfanPkhY0=`. Body `{"customer_id":"78c99d71-f28f-47a9-8302-93b286efbe0e","amount":100.5,"currency":"INR","meta":{"note":"Café","b":2,"a":1}}` gives `l+DvQrzlKbsOSxSYOdWoWHEehcFRZfDJPKlLDkm2cSI=`.

  Deliver:

  1. A typed `listCustomers` function in this codebase's language and HTTP client. Reuse an existing Zapyd client and signer, or write one small shared client.
  2. Config from `ZAPYD_API_KEY`, `ZAPYD_API_SECRET` and `ZAPYD_BASE_URL`. The secret stays on the server, never in a browser or app.
  3. Return `data`. When `status` is false, throw an error with the HTTP status, `err_code`, `message` and `errors`. Don't show raw errors to end users.
  4. Retry only 429 and 5xx: exponential backoff from 1 s, capped at 30 s, at most 5 attempts.
  5. Amounts as strings. Types for every field above.
  6. Tests: the signer against the test vector, and this call against sandbox.

  Reference: `https://docs.zapyd.com/api-reference-exchange/endpoint/customer/list.md`
</Prompt>

| API Status Code | Response | Reason |
| - | - | - |
| 500 | Internal Server Error. | Internal Server Error |


## OpenAPI

````yaml GET /customer/list
openapi: 3.1.0
info:
  title: Zapyd API
  description: API for Zapyd - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.zapyd.com/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
  - url: https://sandbox.zapyd.com/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /customer/list:
    get:
      tags:
        - Customer
      description: List all customers
      parameters:
        - name: search
          in: query
          required: false
          description: >-
            Search by name, email, phone, client_reference_id or customer id
            (min 3 characters)
          schema:
            type: string
          example: john
        - name: country
          in: query
          required: false
          description: Filter by ISO alpha-3 country code
          schema:
            type: string
          example: IND
        - name: customer_status
          in: query
          required: false
          description: Filter by customer status
          schema:
            type: string
          example: VERIFIED
        - name: customer_type
          in: query
          required: false
          description: Filter by customer type
          schema:
            type: string
            enum:
              - INDIVIDUAL
              - BUSINESS
              - UBO
        - name: start_date
          in: query
          required: false
          description: >-
            Created on or after (YYYY-MM-DD). Applied only together with
            end_date.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: >-
            Created on or before (YYYY-MM-DD). Applied only together with
            start_date.
          schema:
            type: string
            format: date
        - name: order_by
          in: query
          required: false
          description: Sort field; prefix with - for descending
          schema:
            type: string
            default: '-created_at'
          example: '-created_at'
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          required: false
          description: Results per page (10–100)
          schema:
            type: integer
            minimum: 10
            maximum: 100
            default: 20
      responses:
        '200':
          description: List of customers fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 1
                      next:
                        type: string
                        nullable: true
                        example: null
                      previous:
                        type: string
                        nullable: true
                        example: <url>
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: 550e8400-e29b-41d4-a716-446655440000
                            status:
                              type: string
                              example: VERIFIED
                            full_name:
                              type: string
                              example: John Doe
                            email:
                              type: string
                              example: john.doe@example.com
                            phone:
                              type: string
                              example: '+1234567890'
                            country:
                              type: string
                              example: USA
                            client_reference_id:
                              type: string
                              example: cust_12345
                            type:
                              type: string
                              example: INDIVIDUAL
                            failure_reason:
                              type: 'null'
                              example: null
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
                  data:
                    type: 'null'
                  err_code:
                    type: string
                    example: SYS_INTERNAL_ERROR
                  errors:
                    type: string
                    example: Unexpected error occurred. Please try again later.
      servers:
        - url: https://sandbox.zapyd.com/cms/api/v1
          description: Customer API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````

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