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

# Create an onboarding request

> Starts onboarding for **USD** (→ `WIRE`) or **EUR** (→ `SEPA`). Returns the case with `requirements.schema` (JSON Schema Draft 07) describing exactly what to submit. The flow is fully headless: you collect the data in your own UI and submit it here — customers are never redirected to a provider-hosted KYC page. NGN/GHS flows need no customer profile. Idempotent: returns the open case if one exists; 409 if the customer is already approved for the feature.

**Flow:** create → (optional) `GET …/terms` → upload documents → `submit` → watch `customer_onboarding.*` webhooks or poll the case → create a virtual account once `approved`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/customers/{customerId}/onboarding-requests
openapi: 3.0.3
info:
  title: XentFi API
  version: 1.0.0
  description: >-
    API documentation for XentFi.The XentFi API gives you access to pretty much
    all the features you can use on our dashboard and lets you extend them for
    use in your application. It strives to be RESTful and is organized around
    the main resources you would be interacting with - with a few notable
    exceptions.
servers:
  - url: https://api.xentfi.com
    description: Production server
security: []
tags: []
paths:
  /v1/customers/{customerId}/onboarding-requests:
    post:
      tags:
        - Customer Onboarding
      summary: Create an onboarding request
      description: >-
        Starts onboarding for **USD** (→ `WIRE`) or **EUR** (→ `SEPA`). Returns
        the case with `requirements.schema` (JSON Schema Draft 07) describing
        exactly what to submit. The flow is fully headless: you collect the data
        in your own UI and submit it here — customers are never redirected to a
        provider-hosted KYC page. NGN/GHS flows need no customer profile.
        Idempotent: returns the open case if one exists; 409 if the customer is
        already approved for the feature.


        **Flow:** create → (optional) `GET …/terms` → upload documents →
        `submit` → watch `customer_onboarding.*` webhooks or poll the case →
        create a virtual account once `approved`.
      operationId: createOnboardingRequest
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - currency
              properties:
                currency:
                  type: string
                  enum:
                    - USD
                    - EUR
      responses:
        '201':
          description: Onboarding case
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      customerId:
                        type: string
                        format: uuid
                      feature:
                        type: string
                        enum:
                          - WIRE
                          - SEPA
                        description: USD → WIRE, EUR → SEPA
                      currency:
                        type: string
                      mode:
                        type: string
                        enum:
                          - api_only
                      status:
                        type: string
                        enum:
                          - draft
                          - collecting_information
                          - submitted
                          - action_required
                          - in_review
                          - approved
                          - rejected
                          - failed
                          - expired
                      requirements:
                        type: object
                        properties:
                          mode:
                            type: string
                          status:
                            type: string
                            enum:
                              - draft
                              - collecting_information
                              - submitted
                              - action_required
                              - in_review
                              - approved
                              - rejected
                              - failed
                              - expired
                          schema:
                            type: object
                            nullable: true
                            description: >-
                              JSON Schema Draft 07 for the `data` you submit.
                              Null once approved.
                      outstandingRequirements:
                        type: array
                        items:
                          type: string
                      rejectionReason:
                        type: string
                        nullable: true
                      submissionCount:
                        type: integer
                      submittedData:
                        type: object
                        nullable: true
                        description: Echo of your submission with identity numbers masked
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '400':
          description: Unsupported currency
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NOT_FOUND
                      message:
                        type: string
                        example: Wallet not found
                      timestamp:
                        type: string
                        format: date-time
                      requestId:
                        type: string
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NOT_FOUND
                      message:
                        type: string
                        example: Wallet not found
                      timestamp:
                        type: string
                        format: date-time
                      requestId:
                        type: string
        '409':
          description: Already approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NOT_FOUND
                      message:
                        type: string
                        example: Wallet not found
                      timestamp:
                        type: string
                        format: date-time
                      requestId:
                        type: string
      security:
        - ApiKeyAuth: []
          OrgIdAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apiKey
    OrgIdAuth:
      type: apiKey
      in: header
      name: orgId

````

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