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

# List Customers

> Retrieve a paginated list of all customers in your account

<ParamField header="Authorization" type="string" required>
  Bearer token: `Bearer YOUR_ACCESS_TOKEN`
</ParamField>

<ParamField body="page" type="number">
  Page number for pagination. Default: `1`
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Default: `20`, max: `100`
</ParamField>

<ParamField body="status" type="string">
  Filter by customer status. Accepted values: `active`, `suspended`, `pending`
</ParamField>

<ParamField body="search" type="string">
  Search by email or name (partial match supported).
</ParamField>

<ParamField body="customerId" type="string">
  Pass a specific customer ID to retrieve a single customer instead of the full list.
</ParamField>

<Accordion title="Response Type Definitions">
  ```typescript theme={null}
  interface Customer {
    id: string;
    email: string;
    first_name: string;
    last_name: string;
    status: "active" | "suspended" | "pending";
    kyc_status: "not_started" | "pending" | "approved" | "rejected";
    created_at: string;
    updated_at: string;
  }

  interface ListCustomersResponse {
    status: "success";
    data: {
      customers: Customer[];
      pagination: {
        page: number;
        limit: number;
        total: number;
        total_pages: number;
      };
    };
  }
  ```
</Accordion>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://crypto-api.yativo.com/api/v1/customers/get-customers' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```typescript TypeScript SDK theme={null}
  const customers = await sdk.customers.list({ page: 1, limit: 20 });
  console.log(customers.data.customers);
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": [
      {
        "_id": "cust_67d01994740754bbf304abcd",
        "username": "alice_merchant",
        "email": "alice@example.com",
        "phone_number": "+1234567890",
        "user_id": "usr_6615c3a1e55d9ff7bc0a1234",
        "createdAt": "2026-01-11T11:08:04.559Z",
        "updatedAt": "2026-01-11T11:08:04.559Z"
      },
      {
        "_id": "cust_67d2d2a5740754bbf308efgh",
        "username": "bob_trader",
        "email": "bob@example.com",
        "phone_number": "",
        "user_id": "usr_6615c3a1e55d9ff7bc0a1234",
        "createdAt": "2026-01-13T12:42:13.562Z",
        "updatedAt": "2026-01-13T12:42:13.562Z"
      }
    ],
    "status": true
  }
  ```
</ResponseExample>