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

# List customers

> Returns customers belonging to the authenticated business, newest first. Archived customers are never included. An unknown filter or sort key is rejected by name rather than ignored, so a typo cannot silently widen a result set.

## Filtering

Filters are written as `field=value`, or `field:operator=value` where the field supports more than equality. A repeated parameter and a comma-separated one mean the same thing, so `type:in=individual&type:in=business` and `type:in=individual,business` are equivalent.

```http
GET /v1/customers?type=individual&tier:gte=1&createdAt:gte=2026-08-01T00:00:00Z&sort=-createdAt&pageSize=50
```

Every rejected parameter is named in the `errors` array, so three bad filters are reported at once rather than one request at a time.

## Error codes

| Status | `code` | Cause |
| - | - | - |
| `400` | `validation_failed` | An unknown filter or sort key, an unsupported operator, a page below 1, or a page size above 100. |
| `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. |
| `404` | `client_not_found` | The key authenticated, but its business no longer exists. |
| `409` | `client_not_a_business` | Customer management is available only to business clients. |
| `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. |


## OpenAPI

````yaml /openapi.json get /v1/customers
openapi: 3.1.0
info:
  title: Sakawave Business API
  version: 1.0.0-draft
  summary: >-
    Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave
    businesses.
  description: >-
    Generated from the public NestJS controllers and their Zod request schemas.
    Public URLs and policy statements remain draft until the Phase 1 contract
    checklist is approved.
  contact:
    name: Sakawave API Support
    email: api-support@sakawave.example
servers:
  - url: https://sandbox-api.sakawave.example
    description: Sandbox (default)
  - url: https://api.sakawave.example
    description: Live
security:
  - bearerAuth: []
tags:
  - name: Bill payments
    description: Browse the biller catalog, validate a customer, and pay a bill.
  - name: Cards
    description: Issue, fund, and control USD virtual and disposable cards.
  - name: eSIM
    description: >-
      Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it
      once installed.
  - name: Currencies and countries
    description: >-
      Reference data: what may be held, what may be sent where, and which
      jurisdictions are served.
  - name: Customers
    description: Create and manage customers of your business.
  - name: Accounts
    description: >-
      Open business and customer accounts, and issue the destinations that fund
      them.
  - name: Transfer destinations
    description: Resolve temporary destinations and saved recipients.
  - name: FX quotes
    description: Create and retrieve time-limited cross-currency quotes.
  - name: Transfers
    description: Preview, create, and monitor transfers.
  - name: Transactions
    description: Read ledger entries for reconciliation.
paths:
  /v1/customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: >-
        Returns customers belonging to the authenticated business, newest first.
        Archived customers are never included. An unknown filter or sort key is
        rejected by name rather than ignored, so a typo cannot silently widen a
        result set.
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          required: false
          description: One-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          required: false
          description: >-
            Records per page. A larger value is rejected rather than capped, so
            your paging arithmetic stays correct.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: search
          in: query
          required: false
          description: >-
            Case-insensitive term matched against name, firstName, lastName,
            email, and externalReference. Maximum 100 characters.
          schema:
            type: string
            maxLength: 100
        - name: sort
          in: query
          required: false
          description: >-
            Up to three comma-separated keys from name, firstName, lastName,
            tier, and createdAt. Prefix a key with - for descending order.
          schema:
            type: string
          example: '-createdAt'
        - name: name
          in: query
          required: false
          description: Exact match on the stored name.
          schema:
            type: string
        - name: firstName
          in: query
          required: false
          description: Exact match. Individual customers only.
          schema:
            type: string
        - name: lastName
          in: query
          required: false
          description: Exact match. Individual customers only.
          schema:
            type: string
        - name: email
          in: query
          required: false
          description: Exact match on the stored, lowercased address.
          schema:
            type: string
            format: email
        - name: externalReference
          in: query
          required: false
          description: Exact match on your own reference.
          schema:
            type: string
          example: cust_1001
        - name: type
          in: query
          required: false
          description: Filter by customer type.
          schema:
            type: string
            enum:
              - individual
              - business
        - name: type:in
          in: query
          required: false
          description: Comma-separated customer types.
          schema:
            type: string
          example: individual,business
        - name: jurisdiction
          in: query
          required: false
          description: ISO 3166-1 alpha-2 country of the customer relationship.
          schema:
            type: string
            minLength: 2
            maxLength: 2
          example: NG
        - name: jurisdiction:in
          in: query
          required: false
          description: Comma-separated country codes. At most 50.
          schema:
            type: string
          example: NG,GH
        - name: tier
          in: query
          required: false
          description: Exact tier. Customers are created at tier 1.
          schema:
            type: integer
            minimum: 1
            maximum: 3
        - name: tier:gte
          in: query
          required: false
          description: Tier at or above this value.
          schema:
            type: integer
            minimum: 1
            maximum: 3
        - name: tier:lte
          in: query
          required: false
          description: Tier at or below this value.
          schema:
            type: integer
            minimum: 1
            maximum: 3
        - name: createdAt:gte
          in: query
          required: false
          description: Created at or after this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: createdAt:lte
          in: query
          required: false
          description: Created at or before this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful response.
          headers:
            X-Request-ID:
              description: >-
                The request identifier assigned by Sakawave. Include it in
                support requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPage'
              example:
                items:
                  - id: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
                    type: individual
                    jurisdiction: NG
                    externalReference: cust_1001
                    displayName: Ada Okafor
                    name: null
                    firstName: Ada
                    middleName: null
                    lastName: Okafor
                    email: ada@example.com
                    phoneNumber: '+2348012345678'
                    dateOfBirth: '1992-04-18'
                    gender: female
                    address:
                      line1: 14 Marina Road
                      line2: null
                      city: Lagos
                      state: Lagos
                      postalCode: '100001'
                      country: NG
                    tier: 1
                    hasBvn: true
                    hasNin: false
                    hasPassport: false
                    hasDriversLicence: false
                    hasTaxId: false
                    hasRegistrationNumber: false
                    createdAt: '2026-08-14T09:00:00.000Z'
                    updatedAt: '2026-08-14T09:00:00.000Z'
                pagination:
                  page: 1
                  pageSize: 25
                  total: 1
                  pageCount: 1
                  hasNext: false
                  hasPrevious: false
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    CustomerPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CustomerResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - items
        - pagination
    CustomerResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
        type:
          type: string
          enum:
            - individual
            - business
          description: Fixed at creation. It decides which of the fields below apply.
        jurisdiction:
          type: string
          minLength: 2
          maxLength: 2
          description: >-
            Uppercase ISO 3166-1 alpha-2 country of the relationship. Fixed at
            creation.
        externalReference:
          anyOf:
            - type: string
              description: >-
                Your own reference. Unique among your customers that are not
                archived.
            - type: 'null'
        displayName:
          type: string
          description: >-
            The business name, or the personal names joined, or "Unnamed
            customer" when neither is on file. Always safe to render.
        name:
          anyOf:
            - type: string
            - type: 'null'
        firstName:
          anyOf:
            - type: string
            - type: 'null'
        middleName:
          anyOf:
            - type: string
            - type: 'null'
        lastName:
          anyOf:
            - type: string
            - type: 'null'
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
        phoneNumber:
          anyOf:
            - type: string
            - type: 'null'
        dateOfBirth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
                - other
            - type: 'null'
        address:
          type: object
          additionalProperties: false
          properties:
            line1:
              anyOf:
                - type: string
                - type: 'null'
            line2:
              anyOf:
                - type: string
                - type: 'null'
            city:
              anyOf:
                - type: string
                - type: 'null'
            state:
              anyOf:
                - type: string
                - type: 'null'
            postalCode:
              anyOf:
                - type: string
                - type: 'null'
            country:
              anyOf:
                - type: string
                - type: 'null'
          required:
            - line1
            - line2
            - city
            - state
            - postalCode
            - country
        tier:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: >-
            Verification tier. Every customer is created at tier 1. It becomes 3
            when the customer passes verification, announced by
            `customer.kyc.approved`. No endpoint sets it directly, and a later
            suspension does not lower it.
        hasBvn:
          type: boolean
          description: Whether a BVN is on file. The number itself is never returned.
        hasNin:
          type: boolean
          description: Whether a NIN is on file.
        hasPassport:
          type: boolean
          description: Whether a passport number is on file.
        hasDriversLicence:
          type: boolean
          description: Whether a driving licence number is on file.
        hasTaxId:
          type: boolean
          description: Whether a tax identifier is on file.
        hasRegistrationNumber:
          type: boolean
          description: >-
            Whether a company registration number is on file. Business customers
            only.
        createdAt:
          $ref: '#/components/schemas/IsoTimestamp'
        updatedAt:
          $ref: '#/components/schemas/IsoTimestamp'
      required:
        - id
        - type
        - jurisdiction
        - externalReference
        - displayName
        - name
        - firstName
        - middleName
        - lastName
        - email
        - phoneNumber
        - dateOfBirth
        - gender
        - address
        - tier
        - hasBvn
        - hasNin
        - hasPassport
        - hasDriversLicence
        - hasTaxId
        - hasRegistrationNumber
        - createdAt
        - updatedAt
    Pagination:
      type: object
      additionalProperties: false
      properties:
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        pageCount:
          type: integer
          minimum: 0
        hasNext:
          type: boolean
        hasPrevious:
          type: boolean
      required:
        - page
        - pageSize
        - total
        - pageCount
        - hasNext
        - hasPrevious
    RequestError:
      anyOf:
        - $ref: '#/components/schemas/ValidationError'
        - $ref: '#/components/schemas/Error'
      description: >-
        Either a field-level validation failure carrying an errors array, or a
        rule the request broke, identified by code.
    Error:
      type: object
      additionalProperties: true
      properties:
        statusCode:
          type: integer
        message:
          type: string
          description: >-
            A sentence suitable for a log or a support conversation, not for a
            user interface.
        code:
          type: string
          description: >-
            The stable machine-readable reason. Branch on this, never on the
            message.
      required:
        - message
        - code
      description: >-
        An error body. Individual errors may add context fields alongside these
        three.
    RateLimitError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 429
        message:
          type: string
        code:
          const: api_key_rate_limit_exceeded
        retryAfterSeconds:
          type: integer
          minimum: 1
      required:
        - statusCode
        - message
        - code
        - retryAfterSeconds
    Ulid:
      type: string
      minLength: 26
      maxLength: 26
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
      description: A 26-character ULID.
    IsoTimestamp:
      type: string
      format: date-time
      example: '2026-08-14T09:00:00.000Z'
    ValidationError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 400
        message:
          type: string
          description: The single failure, or a count when more than one field failed.
        code:
          const: validation_failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationFailure'
      required:
        - statusCode
        - message
        - code
        - errors
    ValidationFailure:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        field:
          type: string
        code:
          type: string
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
      required:
        - message
        - field
        - code
        - path
  responses:
    ValidationError:
      description: >-
        The request was rejected before it was acted on. Field failures list
        every failing field.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
          example:
            statusCode: 400
            message: Must be a valid identifier.
            code: validation_failed
            errors:
              - message: Must be a valid identifier.
                field: accountId
                code: custom
                path:
                  - accountId
    AuthenticationError:
      description: >-
        The API key is missing, invalid, inactive, expired, for another
        environment, or blocked by its IP allowlist.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            code: INVALID_API_KEY
            message: Invalid or inactive API credentials.
    NotFoundError:
      description: The requested resource was not found for this business.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            code: resource_not_found
            message: Resource not found.
    ConflictError:
      description: The request conflicts with the current resource state.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 409
            code: resource_conflict
            message: The request conflicts with the current resource state.
    RateLimitError:
      description: The API key rate limit was exceeded.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            statusCode: 429
            message: Too many API requests. Try again later.
            code: api_key_rate_limit_exceeded
            retryAfterSeconds: 17
    ServerError:
      description: An unexpected server error occurred.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 500
            code: internal_server_error
            message: An unexpected error occurred.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sakawave API key
      description: >-
        A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox
        or `Bearer sk_live_…` in live.

````

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