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

# Submit a business application

> Send a completed business application to Ledig for review.

**Required scope:** `merchants:write`

Use your institution's credentials and keep your institution selected in the business headers. The businessId in the path identifies the business whose application you manage. Your institution must have managed-business access and an active relationship with that business. You can complete its application before that business is approved. Complete the required sections and document uploads first. Before making changes, read the section list and send its exact updatedAt value, in quotes, as If-Match. Use the returned ETag for your next change. A missing or outdated required revision returns 409; fetch the latest application before trying again. Check the application status afterwards for the outcome or any corrections requested.


## OpenAPI

````yaml /openapi/public.yaml post /v1/managed-businesses/{businessId}/onboarding/submit
openapi: 3.1.0
info:
  title: Ledig payments API
  version: 0.1.0
  description: >-
    Use the Ledig payments engine to receive funds, view balances, convert
    currencies and send payments.


    Choose Sandbox to test your integration or Live for production payments.
    Each endpoint explains the fields, permissions and errors you need to
    handle.


    Sign API requests with your business API key and HMAC-SHA256. Endpoints
    listing BearerAuth also accept a user access token. Follow
    https://docs.ledig.io/auth/authentication to sign your requests.
  contact:
    name: Ledig
    email: support@ledig.io
    url: https://docs.ledig.io
servers:
  - url: https://api-sandbox.ledig.io
    description: Sandbox
  - url: https://api.ledig.io
    description: Live
security:
  - LedigApiKey: []
    LedigTimestamp: []
    LedigSignature: []
tags:
  - name: Managed businesses
    description: Onboarding for businesses you manage.
  - name: System
    description: Health and availability.
  - name: Balances
    description: Your available and reserved funds by currency.
  - name: Currencies and rates
    description: Supported currencies, networks and indicative rates.
  - name: Funding accounts
    description: Fiat accounts that receive customer deposits.
  - name: Deposit wallets
    description: Crypto addresses that receive customer deposits.
  - name: Recipients
    description: Saved payout destinations.
  - name: Ledig businesses
    description: Find a business before paying through the Ledig network.
  - name: Payment options
    description: Available payout methods, fees and limits.
  - name: Quotes
    description: Confirm rates, fees and amounts before sending.
  - name: Transfers
    description: Start and track conversions and payments.
  - name: Transactions
    description: Customer transaction history.
paths:
  /v1/managed-businesses/{businessId}/onboarding/submit:
    parameters:
      - in: path
        name: businessId
        required: true
        schema:
          type: string
        description: >-
          The managed business's ID. Keep your institution selected in the
          authentication headers.
        example: business_example_001
      - $ref: '#/components/parameters/SelectedBusinessId'
      - $ref: '#/components/parameters/ActingBusinessId'
    post:
      tags:
        - Managed businesses
      summary: Submit a business application
      description: Send a completed business application to Ledig for review.
      operationId: parentManagedSubmitOnboardingApplication
      parameters:
        - in: header
          name: If-Match
          required: true
          description: >-
            The exact updatedAt value from the application's section list,
            enclosed in quotes. Required for applications you manage. An
            outdated value returns 409.
          schema:
            type: string
          example: '"2026-01-15T10:00:00.000Z"'
      responses:
        '200':
          description: Application submitted.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/ClientOnboardingApplication'
              example:
                status: success
                data:
                  id: application_example_001
                  businessProfileId: profile_example_001
                  referenceCode: APP-EXAMPLE-001
                  status: submitted
                  applicantType: business
                  businessType: standard
                  countryId: null
                  currentSection: review
                  progressPercent: 100
                  sections:
                    - sectionKey: company
                      sectionOrder: 1
                      status: completed
                    - sectionKey: activity
                      sectionOrder: 2
                      status: completed
                    - sectionKey: ownership
                      sectionOrder: 3
                      status: completed
                    - sectionKey: regulation
                      sectionOrder: 4
                      status: completed
                    - sectionKey: documents
                      sectionOrder: 5
                      status: completed
                    - sectionKey: review
                      sectionOrder: 6
                      status: completed
                  submittedAt: '2026-01-15T10:00:00.000Z'
                  reviewedAt: null
                  reviewReason: null
                  approvedAt: null
                  createdAt: '2026-01-15T10:00:00.000Z'
                  updatedAt: '2026-01-15T10:00:00.000Z'
          headers:
            ETag:
              description: >-
                The quoted edit revision to send as If-Match with your next
                application change.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/InvalidOnboardingDocument'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - BearerAuth: []
        - LedigApiKey: []
          LedigTimestamp: []
          LedigSignature: []
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >-
            import { createHmac } from "node:crypto";


            // Node.js 18+. Set credentials and resource values on your server.

            function required(name) {
              const value = process.env[name];
              if (!value) throw new Error(`Set ${name} before running this example.`);
              return value;
            }


            const baseUrl = process.env.LEDIG_API_BASE_URL ??
            "https://api-sandbox.ledig.io";

            const method = "POST";

            const businessId = required("LEDIG_BUSINESS_ID");

            const path =
            `/v1/managed-businesses/${encodeURIComponent(businessId)}/onboarding/submit`;

            const pathWithQuery = path;

            const rawBody = "";

            const headers = { "Accept": "application/json" };

            // Use the exact updatedAt from your latest GET
            /onboarding/sections.

            headers["If-Match"] =
            JSON.stringify(required("LEDIG_ONBOARDING_REVISION"));

            const timestamp = Math.floor(Date.now() / 1000).toString();

            const payload =
            `${timestamp}.${method}.${pathWithQuery}.${rawBody}`;

            headers["x-ledig-key"] = required("LEDIG_API_KEY");

            headers["x-ledig-timestamp"] = timestamp;

            headers["x-ledig-signature"] = "v1=" + createHmac("sha256",
            required("LEDIG_API_SECRET"))
              .update(payload).digest("base64");

            const response = await fetch(`${baseUrl}${pathWithQuery}`, {
              method,
              headers,
            });

            const result = await response.json();

            // Use result in your application; do not log credentials or upload
            links.

            console.log(response.status);
components:
  parameters:
    SelectedBusinessId:
      in: header
      name: X-Ledig-Business-Id
      required: false
      description: >-
        The business you are acting for. For a managed business, your
        institution must be authorised to act for it and API-key requests must
        use HMAC v2. Set this header explicitly; a business ID in the body does
        not select the business.
      schema:
        type: string
        minLength: 1
      example: institution_example_001
    ActingBusinessId:
      in: header
      name: X-Ledig-Acting-Business-Id
      required: false
      description: >-
        Your institution's business ID when acting for a managed business. It
        must match your API key's owner or an institution you belong to. HMAC v2
        signs the trimmed value, or an empty string when omitted.
      schema:
        type: string
        minLength: 1
      example: institution_example_001
  schemas:
    Success:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          const: success
        message:
          type: string
    ClientOnboardingApplication:
      type: object
      additionalProperties: false
      required:
        - id
        - businessProfileId
        - referenceCode
        - status
        - applicantType
        - countryId
        - currentSection
        - progressPercent
        - sections
        - submittedAt
        - reviewedAt
        - reviewReason
        - approvedAt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        businessProfileId:
          type: string
        referenceCode:
          type: string
        status:
          $ref: '#/components/schemas/ApplicationStatus'
        applicantType:
          type: string
          const: business
        businessType:
          type: string
          enum:
            - standard
            - institutional
        countryId:
          type:
            - string
            - 'null'
        currentSection:
          type: string
        progressPercent:
          type: integer
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ClientOnboardingSectionSummary'
        submittedAt:
          type:
            - string
            - 'null'
        reviewedAt:
          type:
            - string
            - 'null'
        reviewReason:
          type:
            - string
            - 'null'
          description: >-
            The same correction instructions as customerMessage when changes are
            requested.
        approvedAt:
          type:
            - string
            - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
        documentDelivery:
          type: array
          items:
            $ref: '#/components/schemas/ClientOnboardingDocumentDelivery'
        verification:
          type:
            - object
            - 'null'
          additionalProperties: false
          required:
            - attemptId
            - subjects
          properties:
            attemptId:
              type: string
            subjects:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                  - kind
                  - status
                  - required
                properties:
                  id:
                    type: string
                  kind:
                    type: string
                    enum:
                      - company
                      - individual_ubo
                      - corporate_owner
                  relatedPartyId:
                    type: string
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - rejected
                      - changes_requested
                  required:
                    type: boolean
        customerMessage:
          type:
            - string
            - 'null'
          description: Instructions explaining what the applicant needs to correct.
    ApplicationStatus:
      type: string
      enum:
        - draft
        - submitting
        - kyb_provider_action_required
        - submitted
        - under_review
        - approved
        - rejected
        - changes_requested
        - cancelled
    ClientOnboardingSectionSummary:
      type: object
      additionalProperties: false
      required:
        - sectionKey
        - status
      properties:
        sectionKey:
          type: string
          enum:
            - company
            - activity
            - ownership
            - regulation
            - documents
            - review
        sectionOrder:
          type: integer
        status:
          type: string
        data:
          $ref: '#/components/schemas/ClientOnboardingSectionData'
    ClientOnboardingDocumentDelivery:
      type: object
      additionalProperties: false
      required:
        - documentId
        - requirementType
        - documentKind
        - state
        - message
        - requiredAction
        - canReplace
      description: The delivery status and timing for an application document.
      properties:
        documentId:
          type: string
        requirementType:
          type: string
        documentKind:
          type: string
        state:
          type: string
          enum:
            - saved
            - sending
            - sent
            - replacement_required
            - attention_required
        message:
          type:
            - string
            - 'null'
        requiredAction:
          type: string
          enum:
            - none
            - replace_document
            - staff_review
            - check_delivery
            - retry_delivery
        canReplace:
          type: boolean
    Error:
      type: object
      required:
        - status
        - message
        - code
      properties:
        status:
          type: string
          const: error
        message:
          type: string
        code:
          type: string
        details:
          description: >-
            Additional information to help resolve an error, such as a file
            problem, allowed amount range or remaining payment allowance. The
            fields depend on the error code.
          oneOf:
            - type: object
              additionalProperties: false
              description: >-
                File-validation details returned with HTTP 400, 413 or 422
                BAD_REQUEST.
              required:
                - validationCode
                - reasonCode
                - retryable
              properties:
                validationCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                reasonCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                retryable:
                  type: boolean
                  const: false
                documentId:
                  type: string
                  maxLength: 128
                requirementType:
                  type: string
                maxSizeBytes:
                  type: integer
                  minimum: 1
                  maximum: 1073741824
                  description: >-
                    Maximum accepted file size in bytes, when supplied with HTTP
                    413.
            - type: object
              additionalProperties: false
              required:
                - reason
              properties:
                reason:
                  type: string
                  enum:
                    - current_password_incorrect
                    - unsupported_asset_network
                    - recipient_unavailable
                    - recipient_incompatible
                    - payout_method_unavailable
                    - payout_method_incompatible
                    - network_unavailable
                    - quote_expired
                    - quote_already_used
                    - quote_changed
                    - invoice_required
                    - invoice_invalid
                    - amount_invalid
                    - amount_precision_invalid
                    - onboarding_revision_required
                    - onboarding_revision_changed
                    - onboarding_document_kind_mismatch
                precision:
                  type: integer
                  minimum: 0
                  maximum: 18
                  description: >-
                    Allowed number of decimal places when reason is
                    amount_precision_invalid.
            - type: object
              additionalProperties: false
              required:
                - period
                - sourceCurrency
                - requested
                - remaining
                - limit
                - resetsAt
                - timezone
              properties:
                period:
                  type: string
                  enum:
                    - daily
                    - monthly
                sourceCurrency:
                  type: string
                  pattern: ^[A-Z][A-Z0-9]{1,19}$
                requested:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                remaining:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                limit:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
            - type: object
              additionalProperties: false
              required:
                - sourceCurrency
                - minimumAmount
                - maximumAmount
              properties:
                sourceCurrency:
                  type: string
                minimumAmount:
                  type: string
                maximumAmount:
                  type: string
              description: >-
                Returned with HTTP 422 RATE_ROUTE_AMOUNT_OUT_OF_RANGE. These
                limits apply to the amount being converted, in the source
                currency.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - limitUsd
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                limitUsd:
                  type: string
              description: >-
                Returned with HTTP 422 PAYOUT_TRANSACTION_LIMIT_EXCEEDED. This
                per-payment limit uses USD equivalent and is separate from the
                payout method's currency limits.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - remainingUsd
                - resetsAt
                - timezone
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                remainingUsd:
                  type: string
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
              description: >-
                Returned with HTTP 422 PAYOUT_MONTHLY_LIMIT_EXCEEDED. Shows your
                business's remaining monthly allowance and when it resets.
    ClientOnboardingSectionData:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - kind
            - documents
          properties:
            kind:
              type: string
              const: documents
            documents:
              type: array
              items:
                $ref: '#/components/schemas/ClientOnboardingDocument'
        - type: object
          additionalProperties: false
          description: >-
            The applicant's saved answers and related people or organisations.
            Each section has its own fields.
          required:
            - kind
            - value
          properties:
            kind:
              type: string
              enum:
                - company
                - activity
                - ownership
                - regulation
                - review
            value:
              type:
                - object
                - 'null'
              additionalProperties: true
            relatedParties:
              type: array
              items:
                type: object
                additionalProperties: true
    ClientOnboardingDocument:
      type: object
      additionalProperties: false
      description: A receipt for a document attached to the application.
      required:
        - id
        - applicationId
        - businessProfileId
        - requirementType
        - originalFileName
        - mimeType
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        applicationId:
          type:
            - string
            - 'null'
        businessProfileId:
          type: string
        requirementType:
          type: string
        documentKind:
          type: string
        originalFileName:
          type: string
        mimeType:
          type: string
        sizeBytes:
          type: integer
        status:
          type: string
          enum:
            - pending_upload
            - uploaded
            - accepted
            - rejected
            - needs_replacement
            - expired
        uploadedAt:
          type: string
        reviewedAt:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        validation:
          type: object
          additionalProperties: false
          required:
            - status
          properties:
            status:
              type: string
              const: valid
        validationFailure:
          type: object
          additionalProperties: false
          required:
            - reasonCode
          properties:
            reasonCode:
              type: string
              enum:
                - document_unreadable
                - document_type_mismatch
                - document_password_protected
                - document_limits_exceeded
  responses:
    BadRequest:
      description: The request is invalid. Check the error message and submitted fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: BAD_REQUEST
            message: Check the request fields and try again.
    Unauthorized:
      description: >-
        Authentication is missing, invalid or expired. Check your credentials
        and request signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: UNAUTHORIZED
            message: Authentication is required.
    Forbidden:
      description: >-
        Your account is inactive, the business selection is missing, or your
        credentials do not have the required permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: FORBIDDEN
            message: You do not have permission to perform this action.
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: NOT_FOUND
            message: The requested resource was not found.
    Conflict:
      description: >-
        The request conflicts with an existing resource or a newer saved
        version.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: CONFLICT
            message: The request conflicts with the current state of this resource.
    InvalidOnboardingDocument:
      description: >-
        The file could not be accepted because it is unreadable, has the wrong
        type, is password-protected or is too complex to validate. BAD_REQUEST
        includes validationCode or reasonCode, retryable=false, documentId and
        requirementType. Replace the file instead of retrying it automatically.
        Previously accepted documents remain unchanged.
      headers:
        x-onboarding-committed-revision:
          description: >-
            When present on a document-completion or submission 422 response,
            this quoted value is the application's new edit revision for that
            request. Use it only for the matching failed request and preserve
            any other unsaved answers. It is absent on conflicts, outages and
            requests that did not supply a revision.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: BAD_REQUEST
            message: The document could not be read. Upload a readable replacement.
            details:
              validationCode: document_unreadable
              reasonCode: document_unreadable
              retryable: false
              documentId: 11111111-1111-4111-8111-111111111111
              requirementType: incorporation_or_registration_evidence
    RateLimited:
      description: >-
        A request or operation allowance has been reached. Wait before retrying.
        If the endpoint uses an idempotency key, keep the same key for the
        retry.
      headers:
        Retry-After:
          description: The number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        Cache-Control:
          description: >-
            Responses use private, no-store or no-store. Do not cache this
            response.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: RATE_LIMITED
            message: Too many requests. Wait before trying again.
  securitySchemes:
    LedigApiKey:
      type: apiKey
      in: header
      name: x-ledig-key
      description: >-
        Your business API key ID. Keep its secret on your server and use that
        secret to sign each request.
    LedigTimestamp:
      type: apiKey
      in: header
      name: x-ledig-timestamp
      description: The current Unix timestamp in seconds, used in the signed request.
    LedigSignature:
      type: apiKey
      in: header
      name: x-ledig-signature
      description: >-
        The request's HMAC-SHA256 signature. Use the v1= prefix for supported
        own-business requests, or v2= when acting for a managed business with
        signed business-selection headers. Follow the authentication guide to
        construct and sign the exact request.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        A user access token from sign-in. Send Authorization: Bearer followed by
        the token. Use this only on endpoints that list BearerAuth.

````

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