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

# Get Customer

> Retrieve a customer by ID.



## OpenAPI

````yaml GET /v1/customers/{customerId}
openapi: 3.0.3
info:
  title: Stablepay Money API
  description: >
    The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat

    payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank
    transfers.
  version: 0.5.0
  contact:
    name: Stablepay Engineering
    email: hello@stablepay.io
servers:
  - url: https://api.stablepay.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Service liveness check.
  - name: FX
    description: Live FX rate conversion between USDC and local fiat currencies.
  - name: Payments
    description: Submit and track stablecoin-to-fiat payout requests.
  - name: Balances
    description: >-
      Live on-chain USDC and native token balances for the tenant's custody
      wallets.
  - name: Analytics
    description: >-
      Pre-aggregated payment analytics — volume, success rates, corridor
      breakdowns, and daily time series.
  - name: Customers
    description: |
      KYC API for DeFi wallets. Onboard and verify your end-users, then link
      their wallet addresses so verified identity travels with their on-chain
      activity.
  - name: Webhooks
    description: Register endpoints and manage outbound event delivery.
  - name: Admin
    description: >-
      Ops-only endpoints for tenant management and payment operations. Requires
      an admin-scoped API key.
paths:
  /v1/customers/{customerId}:
    get:
      tags:
        - Customers
      summary: Get a customer
      description: Retrieve a customer by ID.
      operationId: getCustomer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
          example: cus_01KXG3R0X8DXTKB849FFFEPT7Y
        - name: refresh
          in: query
          required: false
          schema:
            type: boolean
          description: When true, fetches the live status and verified identity.
      responses:
        '200':
          description: Customer found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                id: cus_01...
                externalId: user001
                type: individual
                countryCode: KE
                kycStatus: review
                kycAttempts: 1
                riskLevel: null
                metadata: {}
                verifiedAt: null
                createdAt: '2023-11-07T05:31:56Z'
                updatedAt: '2023-11-07T05:31:56Z'
                verificationUrl: null
                sessionId: null
                identity: null
                reviewWarnings:
                  - code: COULD_NOT_PERFORM_AML_SCREENING
                    severity: error
                    feature: aml_screenings
                    message: >-
                      Could not retrieve data from KYC for performing AML
                      Screening.
        '404':
          description: Customer not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: Prefixed ULID for this customer.
          example: cus_01KXG3R0X8DXTKB849FFFEPT7Y
        externalId:
          type: string
          example: user001
        type:
          type: string
          enum:
            - individual
            - business
        countryCode:
          type: string
          nullable: true
          example: KE
        kycStatus:
          type: string
          description: >-
            One of none, pending, in_progress, review, approved, declined,
            expired, abandoned.
          example: approved
        kycAttempts:
          type: integer
          example: 1
        riskLevel:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
        verifiedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        verificationUrl:
          type: string
          nullable: true
          description: Hosted verification URL. Returned when a verification is started.
          example: https://verify.didit.me/session/XXXX
        sessionId:
          type: string
          nullable: true
        identity:
          type: object
          nullable: true
          description: The verified identity. Returned only with refresh=true.
        reviewWarnings:
          type: array
          nullable: true
          description: >
            Reasons why the customer isn't approved. This is surfaced to show
            your

            end-user why verification is stuck, declined, or needs action.
            Omitted when the customer is approved or in_progress. Returned only
            with refresh=true.
          items:
            type: object
            properties:
              code:
                type: string
                example: COULD_NOT_PERFORM_AML_SCREENING
              severity:
                type: string
                example: error
              feature:
                type: string
                example: aml_screenings
              message:
                type: string
                example: Could not retrieve data from KYC for performing AML Screening.
            required:
              - code
              - severity
              - feature
              - message
          example:
            - code: COULD_NOT_PERFORM_AML_SCREENING
              severity: error
              feature: aml_screenings
              message: Could not retrieve data from KYC for performing AML Screening.
      required:
        - id
        - externalId
        - type
        - kycStatus
        - kycAttempts
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable error message.
          example: fiatAmount must be a positive number.
      required:
        - statusCode
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Stablepay API key. Include as `Authorization: Bearer <key>`.

````