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

# List customers

> List subaccounts under the top-level account with pagination.


**Performance expectations:**<br />
**p50:** 450 ms, **p99:** 1200 ms.<br />
Measured on successful requests (2xx), server-side only.<br />
[How to interpret these metrics](/performance)


## OpenAPI

````yaml /openapi.yaml get /customers
openapi: 3.1.0
info:
  title: Corpay APIs
  version: 1.0.0
  description: >
    Corpay APIs for customer profile management, card management, transaction
    history, and master data retrieval.
servers:
  - url: https://apigwuat.corpay.com
    description: Test environment
  - url: https://apigw.corpay.com
    description: Production environment
security:
  - oauth2ClientCredentials: []
tags:
  - name: Customer
    description: Customer profile and account lifecycle APIs
  - name: Card
    description: Card retrieval, ordering and lifecycle APIs
  - name: Geosearch
    description: >-
      Search and retrieve detailed information about charging locations and
      stations
  - name: Remote Charging
    description: >-
      Control charging sessions remotely including starting and stopping
      sessions, and monitoring session status
  - name: EV Session
    description: >-
      Access and manage charging session data including history, status, and
      detailed session information
  - name: Transaction
    description: Transaction history APIs
  - name: Master
    description: Master/reference data APIs
  - name: Webhooks
    description: Event callback payloads sent by Corpay
paths:
  /customers:
    get:
      tags:
        - Customer
      summary: List customers
      description: |
        List subaccounts under the top-level account with pagination.
      operationId: listCustomers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Customers page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
              example:
                $ref: '#/components/schemas/CustomerListResponse/example'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CustomerListResponse:
      example:
        customers:
          - customerAccountNumber: '1234567890'
            customerAddress:
              addressLines: 123 Main Street Apt 4B
              city: London
              country: United Kingdom
              countryCode: GBR
              region: Greater London
              zipCode: AB12 3CD
            customerBusinessReference: '123444'
            customerContact:
              emailAddress: john.doe@example.com
              firstName: John
              lastName: Doe
              middleName: A
              mobilePhone: '+447700900123'
              telephone: '+441234567890'
            customerName: John Doe
            status: Active
        hasNextPage: true
        lastPage: true
        nextCursor: '12131'
        totalCount: 100
      properties:
        customers:
          items:
            $ref: '#/components/schemas/Customer'
          type: array
        hasNextPage:
          type: boolean
        lastPage:
          type: boolean
        nextCursor:
          type: string
        totalCount:
          type: integer
      type: object
    Customer:
      example:
        customerAccountNumber: '50000012345'
        customerAddress:
          addressLines: 123 Main Street Suite 5
          city: London
          country: United Kingdom
          countryCode: GBR
          region: Greater London
          zipCode: AB12 3CD
        customerBusinessReference: '10234398'
        customerContact:
          emailAddress: john.doe@example.com
          firstName: John
          lastName: Doe
          middleName: A
          mobilePhone: '+447700900123'
          telephone: '+441234567890'
        customerName: Acme Corp
        status: Active
      properties:
        customerAccountNumber:
          type: string
        customerAddress:
          $ref: '#/components/schemas/Address'
        customerBusinessReference:
          description: Reference to Consumer System Internal Identifier
          type: string
        customerContact:
          $ref: '#/components/schemas/Contact'
        customerName:
          type: string
        status:
          type: string
      required:
        - customerAccountNumber
        - customerName
        - status
      type: object
    Error:
      example:
        errorCode: ER-001
        errorDescription: Invalid request parameters
      properties:
        errorCode:
          type: string
        errorDescription:
          type: string
      required:
        - errorCode
        - errorDescription
      type: object
    Address:
      properties:
        addressLines:
          type: string
        city:
          type: string
        country:
          description: >-
            Country Name, which needs to match from master/all API within
            country[].name
          type: string
        countryCode:
          description: >-
            Country Code, which needs to match from master/all API within
            country[].code
          type: string
        region:
          description: >-
            Region Name, which needs to match from master/all API within
            region[].name
          type: string
        zipCode:
          type: string
      type: object
    Contact:
      properties:
        emailAddress:
          format: email
          type: string
        firstName:
          type: string
        lastName:
          type: string
        middleName:
          type: string
        mobilePhone:
          type: string
        telephone:
          type: string
      type: object
  responses:
    BadRequest:
      content:
        application/json:
          example:
            errorCode: ER-001
            errorDescription: Invalid request parameters
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad request - validation error
    Unauthorized:
      description: Unauthorized - missing or invalid authentication token
    Forbidden:
      description: Forbidden - insufficient permissions
    NotFound:
      description: Not found - resource does not exist
    InternalServerError:
      content:
        application/json:
          example:
            errorCode: ER-012
            errorDescription: >-
              The server encountered an unexpected condition and could not
              complete the request. Please contact Corpay Support.
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal server error
  securitySchemes:
    oauth2ClientCredentials:
      description: >
        Use OAuth2 client credentials to obtain a bearer token.


        Token endpoint:

        `POST <BASE_URL>/keycloak/realms/longship/protocol/openid-connect/token`


        Use the same base URL as the selected API server:

        - Test environment: `https://apigwuat.corpay.com`

        - Production environment: `https://apigw.corpay.com`


        Example:

        ```bash

        curl --location
        '<BASE_URL>/keycloak/realms/longship/protocol/openid-connect/token' \

        --header 'accept: application/json' \

        --data-urlencode 'grant_type=client_credentials' \

        --data-urlencode 'client_id=.......' \

        --data-urlencode 'client_secret=......'

        ```
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /keycloak/realms/longship/protocol/openid-connect/token
      type: oauth2

````