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

> ## Agent Instructions
> Money amounts are always major-unit decimal strings (e.g. "1000.00"), never floats and never minor units, in every request, response, and webhook payload.
> Authentication is OAuth 2.0 client credentials: exchange the Client ID and Client Secret at the Token URL for a 24-hour JWT and cache it; do not request a token per call.
> Set a unique clientRef on every money-moving request; it is the idempotency key, and retries return the original resource.
> Quotes are single-use, intent-locked, and expire fast: always read expiresAt, consume the quote with the executor matching its intent, and re-quote on expiry instead of retrying.
> Prefer webhooks over polling for payout, order, and deposit status tracking.
> Use the sandbox (api.sandbox.zuba.com) with its deterministic magic values before touching production.

# Create a KYB/KYC application

> Supports both `business` (KYB) and `individual` (KYC) applications, in any corridor. Identity is verified from an uploaded government-ID document (`photo_id`): a business submits each director’s / applicant’s photo_id, an individual submits the applicant’s photo_id — uploaded via the /documents endpoints before /submit.



## OpenAPI

````yaml /openapi.json post /v2/applications
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Comprehensive payment platform API supporting fiat and crypto payments,
    currency conversion, and compliance management
  title: Zuba Payment Platform API
  version: '1.0'
servers: []
security: []
tags:
  - description: Manage M2M API keys and credentials
    name: API Keys
  - description: Internal ledger accounts and transactions
    name: Ledger
  - description: Handle incoming payments and deposits
    name: Pay-ins
  - description: Manage payouts, beneficiaries, and SEPA transfers
    name: Payouts
  - description: Manage outbound webhook endpoints and deliveries
    name: Webhooks
paths:
  /v2/applications:
    post:
      tags:
        - Applications (v2)
      summary: Create a KYB/KYC application
      description: >-
        Supports both `business` (KYB) and `individual` (KYC) applications, in
        any corridor. Identity is verified from an uploaded government-ID
        document (`photo_id`): a business submits each director’s / applicant’s
        photo_id, an individual submits the applicant’s photo_id — uploaded via
        the /documents endpoints before /submit.
      operationId: ApplicationV2Controller_create
      parameters:
        - description: >-
            Optional. Names an owned sub-account (UUID) to act on. Omit to act
            on the account the API key resolves to (self). A non-owned id
            returns 403.
          in: header
          name: Zuba-Account-Id
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KybApplicationDto'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationDto'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponseDto'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponseDto'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponseDto'
          description: The account already has an active application
      security:
        - bearer: []
components:
  schemas:
    KybApplicationDto:
      properties:
        applicant:
          $ref: '#/components/schemas/ApplicantDto'
        applicationType:
          enum:
            - business
            - individual
          type: string
        businessActivity:
          $ref: '#/components/schemas/BusinessActivityDto'
        businessInfo:
          $ref: '#/components/schemas/BusinessInfoDto'
        documents:
          description: >-
            Accepted but ignored on create; upload documents via the /documents
            endpoints after the application exists.
          items:
            $ref: '#/components/schemas/DocumentRefDto'
          type: array
        hasIndirectControl:
          type: boolean
        indirectControlDetails:
          type: string
        individualActivity:
          $ref: '#/components/schemas/IndividualActivityDto'
        persona:
          enum:
            - sme
            - large_corp
            - licensed_fi
          type: string
        persons:
          description: >-
            Create-time sugar only. Decomposed to one per-person create. After
            creation, manage persons via the /persons sub-resource.
          items:
            $ref: '#/components/schemas/PersonDto'
          type: array
      required:
        - applicationType
        - applicant
      type: object
    ApplicationDto:
      properties:
        accountId:
          description: The account this application belongs to (self or sub-account).
          format: uuid
          type: string
        applicationType:
          enum:
            - business
            - individual
          type: string
        createdAt:
          format: date-time
          type: string
        editableSections:
          description: >-
            When status is more_info_requested, the sections you may edit and
            resubmit. `applicant` / `businessInfo` / `businessActivity` /
            `individualActivity` are edited via PATCH; `persons` via the
            /persons sub-resource (and covers that person’s own documents);
            `documents` is company-level documents via the /documents
            sub-resource. Empty otherwise.
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        moreInfoReason:
          description: >-
            When status is more_info_requested, the reviewer’s notes describing
            what needs to change. Null otherwise.
          type: string
        riskLevel:
          enum:
            - low
            - medium
            - high
            - prohibited
          type: string
        screeningStatus:
          enum:
            - pending
            - in_progress
            - clear
            - flagged
            - failed
            - timed_out
          type: string
        status:
          enum:
            - draft
            - under_review
            - approved
            - more_info_requested
            - rejected
          type: string
      required:
        - id
        - accountId
        - applicationType
        - status
        - createdAt
      type: object
    GenericErrorResponseDto:
      properties:
        error:
          description: Error type identifier
          example: BAD_REQUEST
          type: string
        message:
          description: Error message
          example: Bad Request
          type: string
        path:
          description: Request path that generated the error
          example: /v1/beneficiaries
          type: string
        statusCode:
          description: HTTP status code
          example: 400
          type: number
        timestamp:
          description: ISO timestamp when the error occurred
          example: '2024-01-15T10:30:00.000Z'
          type: string
      required:
        - statusCode
        - message
        - error
        - timestamp
        - path
      type: object
    ApplicantDto:
      properties:
        applicantDateOfBirth:
          example: '1985-06-15'
          format: date
          type: string
        applicantFirstName:
          type: string
        applicantLastName:
          type: string
        applicantNationalId:
          description: National ID or tax identification number (TIN) for the applicant.
          type: string
        applicantNationality:
          description: ISO 3166-1 alpha-2 country code
          type: string
        applicantPhone:
          type: string
        applicantResidentialAddress:
          allOf:
            - $ref: '#/components/schemas/AddressDto'
          description: >-
            Required for individual applications: the applicant’s residential
            address. Its country is the corridor/eligibility key for an
            individual (there is no country of incorporation).
      required:
        - applicantFirstName
        - applicantLastName
        - applicantDateOfBirth
        - applicantNationality
      type: object
    BusinessActivityDto:
      properties:
        accountPurposes:
          items:
            type: string
          type: array
        accountPurposesOtherDescription:
          type: string
        expectedCounterpartyCountries:
          items:
            type: string
          type: array
        monthlyCryptoVolume:
          description: Major-unit decimal string.
          type: string
        monthlyFiatVolume:
          description: Major-unit decimal string.
          type: string
        sourceOfFunds:
          enum:
            - revenue
            - investment
            - other
          type: string
        sourceOfFundsOther:
          type: string
        targetMarket:
          type: string
      required:
        - sourceOfFunds
        - accountPurposes
        - monthlyFiatVolume
      type: object
    BusinessInfoDto:
      properties:
        businessDescription:
          description: >-
            Description of the business. USD corridors require at least 100
            characters.
          type: string
        countryOfIncorporation:
          description: ISO 3166-1 alpha-2 country of incorporation.
          type: string
        entityType:
          enum:
            - corporation
            - llc_ltd
            - partnership
            - non_profit
            - trust
            - sole_proprietorship
          type: string
        incorporationAddress:
          $ref: '#/components/schemas/AddressDto'
        incorporationDate:
          format: date
          type: string
        industry:
          type: string
        industryOtherDescription:
          type: string
        industrySubtype:
          type: string
        legalName:
          description: Registered legal name of the business.
          type: string
        physicalAddress:
          $ref: '#/components/schemas/AddressDto'
        registrationNumber:
          description: Company registration / incorporation number.
          type: string
        sameAsIncorporation:
          description: When true, physicalAddress equals incorporationAddress.
          type: boolean
        taxId:
          type: string
        tradingName:
          type: string
      required:
        - legalName
        - registrationNumber
        - countryOfIncorporation
        - entityType
        - industry
        - businessDescription
        - incorporationAddress
        - sameAsIncorporation
      type: object
    DocumentRefDto:
      properties:
        documentKey:
          description: Key returned by the document upload endpoint.
          type: string
        documentType:
          enum:
            - certificate_of_incorporation
            - memorandum_articles
            - proof_of_address_company
            - tin_certificate
            - org_chart
            - aml_ctf_policy
            - photo_id
            - photo_id_back
            - proof_of_address_personal
            - bank_statement
          type: string
      required:
        - documentType
        - documentKey
      type: object
    IndividualActivityDto:
      properties:
        applicantAccountPurposes:
          items:
            type: string
          type: array
        applicantEmploymentStatus:
          type: string
        applicantExpectedCounterpartyCountries:
          items:
            type: string
          type: array
        applicantExpectedCryptoMonthlyVolume:
          description: Major-unit decimal string.
          type: string
        applicantExpectedFiatMonthlyVolume:
          description: Major-unit decimal string.
          type: string
        applicantSourceOfFunds:
          items:
            type: string
          type: array
        applicantSourceOfWealth:
          items:
            type: string
          type: array
      type: object
    PersonDto:
      properties:
        bvn:
          description: Bank Verification Number (Nigeria).
          type: string
        dateOfBirth:
          example: '1985-06-15'
          format: date
          type: string
        emailAddress:
          format: email
          type: string
        firstName:
          type: string
        lastName:
          type: string
        middleName:
          type: string
        nationalId:
          type: string
        nationality:
          description: ISO 3166-1 alpha-2 country code
          type: string
        ownershipPercentage:
          maximum: 100
          minimum: 0
          type: number
        phoneNumber:
          type: string
        residentialAddress:
          $ref: '#/components/schemas/AddressDto'
        role:
          enum:
            - director
            - shareholder
            - director_and_shareholder
            - signing_officer
          type: string
        title:
          type: string
      required:
        - role
        - firstName
        - lastName
        - dateOfBirth
        - nationality
        - title
        - emailAddress
        - phoneNumber
        - residentialAddress
      type: object
    AddressDto:
      properties:
        city:
          type: string
        country:
          description: ISO 3166-1 alpha-2
          type: string
        postalCode:
          type: string
        state:
          type: string
        street:
          type: string
      required:
        - street
        - city
        - state
        - postalCode
        - country
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: Enter Auth0 JWT token
      scheme: bearer
      type: http

````