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

# Initiate customer KYC

> Retrieve a url that when launched displays a UI that commences KYC for your user



## OpenAPI

````yaml /openapi/customer-20260203.json post /accounts/customers/{customerId}/kyc/initiate
openapi: 3.1.0
info:
  title: CUSTOMER
  termsOfService: urn:tos
  license:
    name: Apache 2.0
    url: https://springdoc.org
  version: '2026-02-03'
  description: ''
servers:
  - url: https://api-sb.meld.io
    description: Meld API sandbox
  - url: https://api.meld.io
    description: Meld API production
security: []
tags:
  - name: Virtual Account
    description: ''
  - name: Customers
paths:
  /accounts/customers/{customerId}/kyc/initiate:
    post:
      tags:
        - Customers
      summary: Initiate customer KYC
      description: >-
        Retrieve a url that when launched displays a UI that commences KYC for
        your user
      operationId: accounts-customers-kyc-initiate
      parameters:
        - name: customerId
          in: path
          description: Customer id
          required: true
          schema:
            type: string
            default: ''
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateKycRequest'
            example:
              mode: HOSTED_URL
              serviceProvider: SUMSUB
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InitiateKycResponse'
        '400':
          description: 'Bad Request : check request values and format'
        '401':
          description: Invalid credentials
        '403':
          description: Unauthenticated or authenticated with insufficient access
        '404':
          description: Customer not found
          content:
            '*/*':
              schema:
                additionalProperties:
                  default: ''
                default: ''
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: KYC already initiated for this customer and provider
          content:
            '*/*':
              schema:
                additionalProperties:
                  default: ''
                default: ''
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Customer is not compliant for KYC sharing
          content:
            '*/*':
              schema:
                additionalProperties:
                  default: ''
                default: ''
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Server Error. This applies to all 5xx errors, including but not
            limited to 500, 501, 502, 503, and 504 errors. You should treat all
            of these errors the same.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    InitiateKycRequest:
      type: object
      description: Request to initiate KYC for a customer with a given provider
      properties:
        kycShareProviders:
          type: array
          description: Additional KYC providers to share the result with
          items:
            type: string
            enum:
              - ACROSS
              - AEROPAY
              - AKOYA
              - ALCHEMYPAY
              - APPLEPAY
              - AUTHORIZENET
              - BANXA
              - BILIRA
              - BINANCECONNECT
              - BINANCEPAY
              - BLOCKCHAINDOTCOM
              - BOOMFI
              - BRAINTREE
              - BRALE
              - BTCDIRECT
              - CASHAPP
              - CHECKOUT
              - CIRCLE
              - COINBASEPAY
              - COINFLOW
              - DUENETWORK
              - ELDORADO
              - FINICITY
              - FLASHNET
              - FONBNK
              - GUARDARIAN
              - HARBOUR
              - KOYWE
              - KRYPTONIM
              - MERCURYO
              - MESH
              - MESO
              - MOONPAY
              - MOOV
              - MX
              - NMI
              - NOAH
              - ONMETA
              - ONRAMPMONEY
              - PAYBIS
              - PAYPAL
              - PLAID
              - RAMP
              - REVOLUT
              - ROBINHOOD
              - ROUTERPROTOCOL
              - SALTEDGE
              - SALTEDGEPARTNERS
              - SARDINE
              - SHIFT4
              - SHOPIFY
              - SIMPLEX
              - SKRILLCRYPTO
              - SQUARE
              - STRIPE
              - SUMSUB
              - SWAPPED
              - TANGOCARD
              - TELLER
              - TOPPER
              - TRANSAK
              - TREMENDOUS
              - TRANSFI
              - UNLIMIT
              - UPHOLD
              - WYRE
              - XANPOOL
              - YELLOWCARD
              - YODLEE
          uniqueItems: true
        mode:
          type: string
          description: KYC initiation mode
          enum:
            - HOSTED_URL
            - TOKEN_IMPORT
        serviceProvider:
          type: string
          description: KYC provider to use (currently only SUMSUB is supported)
          enum:
            - SUMSUB
          minLength: 1
        serviceProviderDetails:
          description: >-
            Provider-specific details required for the selected mode. Required
            when mode is TOKEN_IMPORT, null for HOSTED_URL
          allOf:
            - $ref: '#/components/schemas/KycServiceProviderDetails'
      required:
        - mode
        - serviceProvider
    InitiateKycResponse:
      type: object
      description: >-
        Response after initiating KYC: customer/provider/status. Token is
        obtained via getToken once KYC is complete.
      properties:
        customerId:
          type: string
          description: Customer id (Meld)
        serviceProvider:
          type: string
          description: KYC provider
          enum:
            - SUMSUB
        status:
          type: string
          description: Current KYC status
          enum:
            - PENDING
            - APPROVED
            - REJECTED
            - EXPIRED
            - UNKNOWN
        url:
          type: string
          description: URL to start the KYC flow (e.g. Sumsub WebSDK), if applicable.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        displayMessage:
          type: string
        errors:
          type: array
          items:
            type: string
        message:
          type: string
        requestId:
          type: string
        serviceProviderDetails:
          type: object
          additionalProperties: {}
        timestamp:
          type: string
          format: date-time
    KycServiceProviderDetails:
      description: Provider-specific details for KYC initiation
      oneOf:
        - title: SumsubTokenImportKycDetails
          allOf:
            - $ref: '#/components/schemas/SumsubTokenImportKycDetails'
    SumsubTokenImportKycDetails:
      allOf:
        - $ref: '#/components/schemas/KycServiceProviderDetails'
        - type: object
          properties:
            kycToken:
              type: string
              description: Access token issued by the KYC provider
              minLength: 1
            applicantId:
              type: string
              description: Applicant ID from the KYC provider
              minLength: 1
      description: KYC details for TOKEN_IMPORT mode
      required:
        - applicantId
        - kycToken
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      x-default: BASIC <Meld API Key>

````