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

# Get a customer

> Get a customer's details and KYC standing



## OpenAPI

````yaml GET /platform/v1/customers/{id}
openapi: 3.1.0
info:
  title: MoonPay
  version: 1.0.0
servers:
  - url: https://api.moonpay.com
    description: Production Environment
    variables: {}
  - url: https://api.moonpay.dev
    description: Sandbox Environment
    variables: {}
security: []
tags:
  - name: Assets
  - name: Quote
  - name: Customer
  - name: Identity
  - name: Transactions
paths:
  /platform/v1/customers/{id}:
    get:
      tags:
        - Customer
      summary: Get a customer
      description: >-
        Returns the customer identified by `id`, including their KYC standing
        and outstanding requirements. With a secret key, the customer must have
        connected to the partner. With an access token, the token must be bound
        to this customer.
      operationId: CustomersController.get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
                required:
                  - data
                unevaluatedProperties:
                  not: {}
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Access is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevPlatformApiErrorResponse'
      security:
        - AccessTokenAuth: []
        - SecretApiKeyInHeaderAuth: []
components:
  schemas:
    Customer:
      type: object
      required:
        - id
        - externalCustomerId
        - kyc
      properties:
        id:
          type: string
          format: uuid
          description: The customer's unique MoonPay identifier.
        externalCustomerId:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The partner-provided identifier for this customer, if one was
            supplied. Null when the customer connected without an external
            identifier.
        kyc:
          allOf:
            - $ref: '#/components/schemas/CustomerKyc'
          description: KYC details for the customer.
      unevaluatedProperties:
        not: {}
      description: A MoonPay customer as seen by a partner.
    UnauthorizedError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - unauthorized
        message:
          type: string
          enum:
            - Not authorized
      unevaluatedProperties:
        not: {}
      description: Missing or invalid credentials.
    ForbiddenError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - forbidden
        message:
          type: string
          enum:
            - Forbidden
      unevaluatedProperties:
        not: {}
      description: Insufficient permissions.
    DevPlatformApiErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/DevPlatformApiErrorCodes'
          description: Code identifying the error type.
          examples:
            - forbidden
            - unauthorized
            - invalid_request
        message:
          type: string
          description: Human-readable error message.
          examples:
            - Forbidden
            - Not authorized
            - One or more request parameters are invalid.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/DevPlatformErrorDetail'
          description: Optional list of field-level error details.
          examples:
            - - field: source.amount
                message: >-
                  Source amount must be a numeric string. Example "100" or
                  "10.25".
      unevaluatedProperties:
        not: {}
      description: Response body returned when a request fails.
    CustomerKyc:
      type: object
      required:
        - status
        - requirements
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/CustomerKycStatus'
          description: The customer's KYC standing.
        requirements:
          allOf:
            - $ref: '#/components/schemas/Requirements'
          description: Outstanding and completed KYC requirements for the customer.
        challenge:
          allOf:
            - $ref: '#/components/schemas/IdentityVerificationChallenge'
          description: Hosted challenge the partner must surface to the customer.
      unevaluatedProperties:
        not: {}
      description: KYC details for a customer.
    DevPlatformApiErrorCodes:
      type: string
      enum:
        - unknown_error
        - unauthorized
        - forbidden
        - not_found
        - invalid_request
        - not_implemented
        - too_many_requests
        - not_allowed
        - conflict
        - unprocessable_entity
        - sse_timeout
        - sse_error
        - service_unavailable
        - requirements_incomplete
        - requirement_not_pending
        - verification_rejected
        - country_mismatch
        - upload_expired
        - unsupported_country
        - verification_pending
        - kyc_not_approved
        - no_outstanding_requirements
        - terms_accepted_at_out_of_range
    DevPlatformErrorDetail:
      type: object
      required:
        - message
      properties:
        field:
          type: string
          description: Field that caused the error.
        message:
          type: string
          description: Human-readable error message for this field.
        details:
          type: object
          unevaluatedProperties: {}
          description: >-
            Extra data that describes the error in more detail, useful when
            debugging or logging. Keys vary by error and are not part of the API
            contract. For example, an amount-limit error includes the limit
            value as "maxBuyAmount" or "minBuyAmount".
      unevaluatedProperties:
        not: {}
    CustomerKycStatus:
      type: string
      enum:
        - collecting
        - verifying
        - active
        - unavailable
        - not_created
      description: >-
        The customer's KYC standing with you. `not_created` means no KYC session
        exists yet for this customer.
    Requirements:
      type: object
      properties:
        basicDetails:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: >-
            The customer's basic personal details (first name, last name, date
            of birth, nationality).
          examples:
            - status: incomplete
              requiredFields:
                - firstName
                - lastName
                - dateOfBirth
                - nationality
        residentialAddress:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: The customer's residential address.
          examples:
            - status: incomplete
              requiredFields:
                - street
                - locality
                - postalCode
                - administrativeArea
        identityDocuments:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: >-
            Identity document submission (passport, driver's license, residence
            permit, etc.).
          examples:
            - status: incomplete
        selfie:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: Selfie photo submission.
          examples:
            - status: incomplete
        taxIdentifiers:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: Tax identifier submission (SSN, CPF, TIN, etc.).
          examples:
            - status: incomplete
              requiredFields:
                - ssn
        proofOfAddress:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: Proof-of-address document submission.
          examples:
            - status: incomplete
        phoneNumber:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: Customer's phone number in E.164 format.
          examples:
            - status: incomplete
        questionnaires:
          allOf:
            - $ref: '#/components/schemas/RequirementEntry'
          description: >-
            Due-diligence questionnaires the customer must complete (Customer
            Due Diligence and Enhanced Due Diligence). When incomplete,
            `requiredFields` lists the outstanding questionnaire types.
          examples:
            - status: incomplete
              requiredFields:
                - customerDueDiligence
                - enhancedDueDiligence
      unevaluatedProperties:
        not: {}
      description: >-
        Outstanding and completed requirements for the identity, keyed by
        requirement category. Only requirements that apply to the customer are
        present.
    IdentityVerificationChallenge:
      type: object
      required:
        - url
        - expiresAt
      properties:
        url:
          type: string
          description: >-
            Fully-formed challenge URL. Render directly without parsing; the URL
            embeds the challenge token.
        expiresAt:
          type: string
          format: date-time
          description: >-
            Timestamp at which the challenge URL expires. Partners must surface
            the challenge to the customer before this time.
      unevaluatedProperties:
        not: {}
      description: >-
        A MoonPay-hosted challenge a partner must surface to the customer to
        complete identity verification.
    RequirementEntry:
      type: object
      required:
        - status
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/RequirementItemStatus'
          description: Whether the requirement has been completed.
        requiredFields:
          type: array
          items:
            $ref: '#/components/schemas/RequirementFieldName'
          description: >-
            When status is incomplete, the outstanding fields the customer must
            provide for this requirement. Populated for `basicDetails`,
            `residentialAddress`, `taxIdentifiers`, and `questionnaires`;
            omitted when status is complete or for other requirement types,
            which do not surface field-level detail.
      unevaluatedProperties:
        not: {}
      description: Status of a single requirement group on an identity.
    RequirementItemStatus:
      type: string
      enum:
        - incomplete
        - complete
      description: The completion state of a requirement item.
    RequirementFieldName:
      type: string
      enum:
        - firstName
        - lastName
        - dateOfBirth
        - nationality
        - street
        - locality
        - postalCode
        - country
        - administrativeArea
        - ssn
        - cpf
        - tin
        - customerDueDiligence
        - enhancedDueDiligence
      description: >-
        A field a customer must provide to fulfil a requirement. Members match
        the field names used in the requirement-fulfilment endpoints (e.g. PATCH
        /platform/v1/identities/{id}).
  securitySchemes:
    AccessTokenAuth:
      type: http
      scheme: bearer
      description: |-
        Bearer authentication header using an access token.

        Example: `Authorization: Bearer <accessToken>`
    SecretApiKeyInHeaderAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: |-
        Secret key authentication via the `X-Api-Key` header.

        Example: `X-Api-Key: <secretKey>`

````