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

# List Customers

> Retrieves a paginated list of customers.

Retrieve a paginated list of all customers associated with your business.


## OpenAPI

````yaml GET /api/v1/customer
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.8
  description: >-
    Welcome to the Afriex Business API. This API allows you to manage customers,
    process payments, handle payouts, and receive real-time notifications via
    webhooks.


    For detailed guidance on authentication, pagination, error handling, and
    webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
    the top bar. The guide provides a step-by-step instructions to help you
    integrate seamlessly.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: eng@afriex.co
    url: https://docs.afriex.com
  license:
    name: Proprietary
    url: https://www.afriex.com/terms-and-condition
servers:
  - url: https://sandbox.api.afriex.com
    description: Staging Base URL
  - url: https://api.afriex.com
    description: Production Base URL
security:
  - ApiKey: []
tags:
  - name: Customers
    description: Create and manage your customers.
  - name: Payment Methods
    description: Register and resolve customer payout and collection methods.
  - name: Transactions
    description: Create and track deposits, withdrawals, and swaps.
  - name: Balance
    description: View and top up your business wallet balances.
  - name: Rates
    description: Fetch real-time exchange rates.
  - name: Checkout Sessions
    description: Create hosted checkout sessions.
  - name: Webhooks
    description: Webhook event payloads and sandbox webhook testing.
  - name: Media
    description: Generate presigned URLs for secure file uploads.
paths:
  /api/v1/customer:
    parameters:
      - $ref: '#/components/parameters/x-api-version'
    get:
      tags:
        - Customers
      summary: Get customer list
      description: Retrieves a paginated list of customers.
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          description: Page number for pagination (starting from 0)
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: email
          in: query
          description: Filter by customer email address (exact match, case-insensitive).
          required: false
          schema:
            type: string
            format: email
            examples:
              - john.doe@example.com
        - name: phone
          in: query
          description: Filter by customer phone number in E.164 format.
          required: false
          schema:
            type: string
            examples:
              - '+2348192837465'
      responses:
        '200':
          description: List of customers retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  page:
                    type: integer
                    description: Current page number
                  total:
                    type: integer
                    description: Total number of customers matching the query
              examples:
                success:
                  summary: Customer list retrieved
                  value:
                    data:
                      - name: Addams Oshay
                        email: addams@example.com
                        phone: '+15086340138'
                        customerId: 6929843e2c4653277440acc0
                        countryCode: US
                        createdAt: '2025-11-28T11:15:10.812Z'
                        updatedAt: '2025-11-28T11:15:10.812Z'
                      - name: Daniel Obirije
                        email: daniel@example.com
                        phone: '+2347049861191'
                        customerId: 6930610b0d8aab4a00b3f918
                        countryCode: NG
                        createdAt: '2025-12-03T16:10:51.291Z'
                        updatedAt: '2025-12-03T16:10:51.291Z'
                    total: 1448
                    page: 0
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validationError:
                  summary: Validation error
                  value:
                    code: VALIDATION_ERROR
                    error: 'Failed to parse request. Issues: ''page'' must be a number'
                    details: {}
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    code: AUTHENTICATION_ERROR
                    error: Authorization header is missing
                    details: {}
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    code: AUTHENTICATION_ERROR
                    error: Invalid authorization header
                    details: {}
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serverError:
                  summary: Unexpected server error
                  value:
                    code: INTERNAL_SERVER_ERROR
                    error: It's not you, it's us, please reach out to support
                    details: {}
      x-codeSamples:
        - lang: TypeScript
          label: Afriex SDK
          source: |
            const response = await afriex.customers.list({
              page: 0,
              limit: 20,
              email: "john@example.com",
            });

            console.log(response.data);  // Customer[]
            console.log(response.total); // Total count
components:
  parameters:
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
        stable.
      schema:
        type: string
  schemas:
    Customer:
      type: object
      properties:
        customerId:
          type: string
          description: The unique identifier for the customer.
        name:
          type: string
          description: The full name of the customer.
        email:
          type: string
          format: email
          description: The email of the customer.
        phone:
          type: string
          description: The phone number of the customer in E.164 format.
        countryCode:
          type: string
          description: The country code of the customer in ISO 3166-1 alpha-2 format.
        meta:
          type: object
          description: optional meta data you can attach to the customer.
        createdAt:
          type: string
          description: The date and time the customer was created.
        updatedAt:
          type: string
          description: The date and time the customer was last updated.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        errorMessage:
          type: string
          description: Detailed/technical error message.
        friendlyMessage:
          type: string
          description: User-facing error message safe to display.
        data:
          type: object
          description: >-
            Optional caller-safe context for the error. On a customer-create
            uniqueness conflict (EMAIL_ALREADY_EXISTS /
            PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
            id, so you can adopt it without a follow-up lookup.
          properties:
            customerId:
              type: string
              description: Id of the existing customer (on a create conflict).
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Static business API key issued from the dashboard. A business can
        provision **multiple API keys**, each scoped to a configurable set of
        **permissions** (e.g. read transactions, create deposits, etc).
        Permissions are chosen per key at creation time in the dashboard and may
        be revoked by deleting the key. Requests made with a key that does not
        include the permission required by the target endpoint will be rejected
        with a `403 Forbidden` response; an unrecognised, malformed or revoked
        key returns `401 Unauthorized`. Manage your keys and their permissions
        under **Developer → API keys** in the dashboard.

````