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

> ## Agent Instructions
> Bitnob has two APIs. The Business API (payouts, cards, trading, virtual accounts, stablecoin and bitcoin transfers) is at https://api.bitnob.com. The Enterprise API (non-custodial wallets) is at https://api.platform.bitnob.com.
> Business API auth: sign every request with HMAC-SHA256 and send four headers: `X-Auth-Client` (your client ID), `X-Auth-Timestamp` (Unix seconds), `X-Auth-Nonce` (16 random bytes, hex), and `X-Auth-Signature`, the hex HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY` keyed with your client secret. BODY is the exact request body string you send, or an empty string. A missing header, a bad signature, or a timestamp more than about 5 minutes off returns `401`.
> Enterprise API auth: send your key in the `X-API-Key` header. Write requests such as creating a transaction also need an `Idempotency-Key` header, or they fail with `idempotency_key_required` before anything happens.
> Sandbox and production share the Business API base URL. The credentials you sign with select the environment, and `GET /api/whoami` returns it in `data.environment`. Use sandbox credentials in sample code and tests, and never put live credentials in code.
> Amounts are strings unless stated otherwise. Never parse them into floats. Balances, transactions, withdrawals (`POST /api/withdrawals`) and virtual accounts use integer strings in the smallest unit: satoshis for BTC, 6 decimals for USDT and USDC, kobo for NGN, and cents for KES and UGX (100 is 1 KES or 1 UGX). A mobile money collection takes `amount` as a JSON integer in cents.
> Payouts and trading use decimal strings in major units: a payout quote `amount` of `"1"` is 1 USDT, and a trading `quantity` of `"0.0001"` is 0.0001 BTC. Payout responses also carry `cent_amount`, the settlement amount in minor units.
> Card amounts are micro-units (1 USD = 1,000,000). Send them as JSON integers. Card responses return them as integer strings, and card webhooks as integers.
> Generate a unique `reference` for each money movement before the first attempt, and reuse it on retries. A reused reference returns `409` on payout quotes (`ALREADY_EXISTS`), withdrawals (`DUPLICATE_KEY_ERROR`) and card creation (`ALREADY_EXISTS`). It returns the existing record on NGN-pair trading orders, NGN virtual accounts and active mobile money collections. On a mobile money collection that has closed or failed it returns `409` `DUPLICATE_REFERENCE`. It isn't checked on crypto-pair trading orders, so look the order up with `GET /api/trading/orders/{reference}` before resending.
> Quotes expire at `expires_at`; read it from the response instead of assuming a window. An expired trading quote returns `422` `PRECONDITION_FAILED`, and an expired payout quote returns `400` `VALIDATION_ERROR`. Create a new quote rather than retrying. A payout quote can be initialized once, and a trading quote is consumed by the order that fills it.
> Webhooks: verify the `x-bitnob-signature` header, the hex HMAC-SHA512 of the raw request body keyed with your webhook secret, before parsing JSON. Compare in constant time and de-duplicate on `event_id`. A successful API response means accepted: confirm the outcome from the webhook, such as `payouts.withdrawal.success`.
> Errors return `status`, `code` and `detail`. Branch on `code`, never on `detail`. Since the November 5, 2026 response format change, each company gets either the current or the new error codes until its cutoff date, so handle both: `PROVIDER_ERROR` or `PROCESSING_ERROR`, and `BVN_PROVIDER_UNAVAILABLE` or `BVN_VERIFICATION_UNAVAILABLE`. A body that fails to parse returns `{"error": {"code": "BAD_REQUEST"}}`.

# Submit a customer's sender profile for review

> Submits the SWIFT sender profile written with PUT /api/customers/{customerId}. From not_submitted, or rejected before any approval, a complete profile goes to pending and enters Bitnob's compliance review; any other state returns the customer unchanged (after an approval, a PUT that changes identity resubmits by itself). Bitnob sends customers.sender.approved or customers.sender.rejected when the version is decided. In sandbox the submission is decided at once, and sandbox.reject_with rejects it with that reason code. The response is the customer with its sender block. An expiry date already in the past is refused.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json post /api/customers/{customerId}/verify
openapi: 3.1.0
info:
  description: >-
    The Bitnob API for businesses: customers, virtual accounts, mobile money
    collections, cards, payouts, crypto addresses and transfers, Lightning,
    trading and exchange rates.


    ## Authentication

    Every request is signed with your API key's client id and secret.


    **Signed requests (recommended).** Send:

    - `X-Auth-Client`: your client id

    - `X-Auth-Timestamp`: the current Unix time in seconds; requests more than 5
    minutes off are refused

    - `X-Auth-Nonce`: a unique random string of 8 to 128 characters for this
    request

    - `X-Auth-Signature`: hex HMAC-SHA256 of
    `{client_id}:{timestamp}:{nonce}:{body}` using your secret, where body is
    the raw request body (empty for GET)


    **Secret mode.** Send `X-Auth-Client` and `X-Auth-Secret` instead. Simpler,
    but the secret travels with every request.


    Live keys work only for an active organisation; sandbox keys work at any
    time. `ANY /api/whoami` echoes the authenticated client and is the quickest
    way to check your signing.


    ## Responses

    Successful responses are wrapped in an envelope with `success`, `message`,
    `data` and `timestamp`; on lists the paging fields sit inside `data`. Errors
    come either as the envelope with `success: false` and an `error` object, or
    as an RFC 7807 problem with a machine-readable `code`; branch on the code.


    Every response carries an `X-Correlation-ID` header; errors repeat it as
    `request_id`. Quote it to support.



    Every request passes a per-IP rate limit of 500 requests a minute (429 with
    `Retry-After`).



    This document is maintained by hand and checked against the route table on
    every build: every /api route is listed here.
  title: Bitnob API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.bitnob.com
security:
  - BitnobClientId: []
    BitnobClientSecret: []
tags:
  - description: Check that your requests are signed correctly.
    name: Authentication
  - description: >-
      The people and businesses you serve. Creating and editing them needs the
      customers feature.
    name: Customers
  - description: >-
      Naira accounts that receive bank transfers, for your company or for a
      customer.
    name: Virtual accounts
  - description: >-
      One mobile money payment (KES, UGX) requested from a payer's phone and
      credited to your balance. Webhooks for a collection name it
      virtual_account_id; that is the collection id.
    name: Collections
  - description: Crypto deposit addresses, for your company or for a customer.
    name: Addresses
  - description: >-
      Virtual cards: issue, fund, withdraw, freeze, terminate, and the card KYC
      and corporate onboarding behind them.


      ## Card programs


      Every card belongs to one card program, named by `card_program` on card
      KYC, card creation and the card object. A

      program must be enabled for your company before you can use it; otherwise
      the request returns 400.


      | Program | What it is | Funding | Card KYC |

      |---|---|---|---|

      | `prepaid` | Virtual prepaid card. | From your company balance at
      creation, 2 to 2,500 USD. | `POST /api/cards/kyc` with `card_program:
      prepaid`. |

      | `collateral` | A cardholder's own card, backed by a deposit. | No
      initial funding; spending power comes from the deposit. | `POST
      /api/cards/kyc` with `card_program: collateral`; the cardholder finishes
      on the hosted page (`completion_link`). |

      | `collateral_business` | Business cards that draw on one shared company
      pool. | The company pool. | `POST /api/cards/kyc/corporate`. |

      | `prepaid_platinum` | Virtual prepaid USD Visa card. | From your company
      balance at creation, $5 to $2,500; $1 always stays on the card. | `POST
      /api/cards/kyc` with an identity document and `id_front_image`. |

      | `prepaid_premium` | Virtual prepaid USD Visa card, premium range. | As
      `prepaid_platinum`. | As `prepaid_platinum`. |


      For `prepaid_platinum` and `prepaid_premium`:


      - **Register your card encryption key first.** Send your RSA public key
      (2048 bits or more) to
        `POST /api/cards/encryption-key`. These programs only ever return card details encrypted to that key, so until it is
        registered, `GET /api/cards/{cardId}/secure` returns 422 for their cards. Card creation itself does not check for the
        key, so register it before you issue cards. To open the encrypted details, see
        [Decrypt card details](/docs/card-issuing/decrypt-card-details).
      - One card KYC covers both: a customer approved for either can be issued
      cards in both.

      - Create the card with a `customer_id` that has passed card KYC; an inline
      customer is refused.

      - `prepaid` is the default when `card_program` is omitted.
      `prepaid_platinum` and `prepaid_premium` must be named.

      - Card details from `GET /api/cards/{cardId}/secure` are always encrypted
      to your registered key, and are shown through
        `secure_view_url`, a link usable for about one minute.
    name: Cards
  - description: >-
      The company's Card wallet, the USD balance cards are funded from; move
      USDT or USDC into and out of it.
    name: Card wallet
  - description: 'Pay out to bank accounts and mobile money: quote, initialize, finalize.'
    name: Payouts
  - description: Saved payout recipients.
    name: Beneficiaries
  - description: Banks and account lookups for payouts.
    name: Banks
  - description: Balance transfers between Bitnob organisations.
    name: Transfers
  - description: Crypto withdrawals.
    name: Withdrawals
  - description: Lightning invoices and payments.
    name: Lightning
  - description: Lightning addresses, LNURL withdraw links and LNURL payments.
    name: LNURL
  - description: Blockchain node access.
    name: Nodes
  - description: Quotes and orders for buying and selling.
    name: Trading
  - description: Rates and conversions.
    name: Exchange rates
  - description: Your transaction history.
    name: Transactions
  - description: Wallet balances.
    name: Balances
paths:
  /api/customers/{customerId}/verify:
    post:
      tags:
        - Customers
      summary: Submit a customer's sender profile for review
      description: >-
        Submits the SWIFT sender profile written with PUT
        /api/customers/{customerId}. From not_submitted, or rejected before any
        approval, a complete profile goes to pending and enters Bitnob's
        compliance review; any other state returns the customer unchanged (after
        an approval, a PUT that changes identity resubmits by itself). Bitnob
        sends customers.sender.approved or customers.sender.rejected when the
        version is decided. In sandbox the submission is decided at once, and
        sandbox.reject_with rejects it with that reason code. The response is
        the customer with its sender block. An expiry date already in the past
        is refused.
      operationId: customersVerifySender
      parameters:
        - description: ID of the customer.
          example: 019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70
          in: path
          name: customerId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            examples:
              live:
                summary: Submit for review
                value: {}
              sandbox_reject:
                summary: Sandbox key, reject with a reason code
                value:
                  sandbox:
                    reject_with: NAME_MISMATCH
            schema:
              properties:
                sandbox:
                  description: Sandbox keys only; refused on live.
                  properties:
                    reject_with:
                      enum:
                        - DOCUMENT_UNREADABLE
                        - NAME_MISMATCH
                        - ID_EXPIRED
                        - DOCUMENT_TYPE_WRONG
                        - OTHER
                      type: string
                  type: object
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              examples:
                pending:
                  summary: Submitted on live; the version waits for review
                  value:
                    data:
                      card_counts: null
                      city: Lagos
                      company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01
                      country: NGA
                      country_of_birth: NGA
                      created_at: '2026-10-28T14:02:11.482913Z'
                      created_by: 019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12
                      customer_type: individual
                      date_of_birth: '1988-04-17'
                      dial_code: '+234'
                      email: chinedu.okafor@example.com
                      first_name: Chinedu
                      gender: MALE
                      id: 019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70
                      id_expiry_date: '2032-03-13'
                      id_issue_date: '2022-03-14'
                      id_number: A09876543
                      id_type: passport
                      is_active: true
                      kyc_status: ''
                      last_name: Okafor
                      line1: 14 Admiralty Way
                      metadata: ''
                      nationality: NGA
                      phone_number: '8031234567'
                      postal_code: '106104'
                      sender:
                        approved_version: null
                        decided_at: null
                        document:
                          content_type: application/pdf
                          id: 3f7a1c9e-5b2d-4e8f-a6c1-0d9b8e7f6a52
                          kind: sender_id
                          name: proofOfIdentity
                          size_bytes: 241233
                          uploaded_at: '2026-11-05T09:16:05Z'
                        documents:
                          - content_type: application/pdf
                            id: 3f7a1c9e-5b2d-4e8f-a6c1-0d9b8e7f6a52
                            kind: sender_id
                            name: proofOfIdentity
                            size_bytes: 241233
                            uploaded_at: '2026-11-05T09:16:05Z'
                        expires_at: null
                        missing_fields: []
                        rejection: null
                        sender_type: individual
                        state: pending
                        submitted_at: '2026-11-05T09:20:11Z'
                        updated_at: '2026-11-05T09:20:11Z'
                        version: 1
                      state: Lagos
                      updated_at: '2026-11-05T09:20:11Z'
                    message: Sender profile submitted
                    success: true
                    timestamp: '2026-11-05T09:20:11.481Z'
                sandbox_rejected:
                  summary: Sandbox key with reject_with
                  value:
                    data:
                      card_counts: null
                      company_id: 019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01
                      created_at: '2026-10-28T14:02:11.482913Z'
                      created_by: 019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12
                      customer_type: individual
                      email: chinedu.okafor@example.com
                      id: 019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70
                      is_active: true
                      kyc_status: ''
                      metadata: ''
                      sender:
                        approved_version: null
                        decided_at: '2026-11-05T09:20:11Z'
                        document:
                          content_type: application/pdf
                          id: 3f7a1c9e-5b2d-4e8f-a6c1-0d9b8e7f6a52
                          kind: sender_id
                          name: proofOfIdentity
                          size_bytes: 241233
                          uploaded_at: '2026-11-05T09:16:05Z'
                        documents:
                          - content_type: application/pdf
                            id: 3f7a1c9e-5b2d-4e8f-a6c1-0d9b8e7f6a52
                            kind: sender_id
                            name: proofOfIdentity
                            size_bytes: 241233
                            uploaded_at: '2026-11-05T09:16:05Z'
                        expires_at: null
                        missing_fields: []
                        rejection:
                          hint: The name on the document does not match the profile.
                          reason_code: NAME_MISMATCH
                        sender_type: individual
                        state: rejected
                        submitted_at: '2026-11-05T09:20:11Z'
                        updated_at: '2026-11-05T09:20:11Z'
                        version: 1
                      updated_at: '2026-11-05T09:20:11Z'
                    message: Sender profile submitted
                    success: true
                    timestamp: '2026-11-05T09:20:11.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/CustomersCustomer'
                    type: object
          description: OK
        '400':
          content:
            application/json:
              examples:
                expiry_passed:
                  summary: The identity document has already expired
                  value:
                    error:
                      code: BAD_REQUEST
                      details:
                        id_expiry_date: has already passed
                      message: Validation failed
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    success: false
                    timestamp: '2026-11-05T09:15:02.481Z'
                invalid_customer_id:
                  summary: Not a UUID
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: 'invalid customer id: invalid UUID length: 7'
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 400
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Validation Error
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
                sandbox_on_live:
                  summary: The sandbox hook with a live key
                  value:
                    error:
                      code: BAD_REQUEST
                      details:
                        sandbox: is accepted only with a sandbox key
                      message: Validation failed
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    success: false
                    timestamp: '2026-11-05T09:15:02.481Z'
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            sandbox sent with a live key, reject_with is not a reason code, or
            the stored profile fails a format rule (BAD_REQUEST with
            error.details); or the customer id is not a UUID (VALIDATION_ERROR).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          content:
            application/json:
              examples:
                client_inactive:
                  $ref: '#/components/examples/ClientInactive'
                ip_not_whitelisted:
                  $ref: '#/components/examples/IPNotWhitelisted'
                org_not_active_live:
                  $ref: '#/components/examples/OrgNotActiveLive'
                self_row:
                  summary: The customer is the individual workspace owner's own record
                  value:
                    code: FORBIDDEN
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      the workspace owner's own record is kept from their
                      verified identity and cannot be changed here
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 403
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Forbidden
                    type: https://api.bitnob.com/errors/FORBIDDEN
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            Not allowed: the customers feature is off (FEATURE_NOT_ENABLED), the
            customer is the workspace owner's own record (FORBIDDEN), the
            organisation is not active on live (ORG_NOT_ACTIVE), or the key's IP
            allowlist or client status refused it.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '404':
          content:
            application/json:
              examples:
                customer_not_found:
                  summary: Unknown, deleted or another organisation's customer
                  value:
                    code: NOT_FOUND
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      customer with ID '019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70'
                      was not found
                    extensions:
                      id: 019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70
                      resource: customer
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 404
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Resource Not Found
                    type: https://api.bitnob.com/errors/NOT_FOUND
              schema:
                $ref: '#/components/schemas/Problem'
          description: No customer with this id belongs to your organisation (NOT_FOUND).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '422':
          content:
            application/json:
              examples:
                customer_type_ambiguous:
                  summary: customer_type is not exactly individual or business
                  value:
                    code: VALIDATION_FAILED
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      Only a customer whose type is exactly individual or
                      business can be a sender.
                    extensions:
                      customer_type: individual,cardholder
                      error_code: CUSTOMER_TYPE_AMBIGUOUS
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 422
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Customer Type Ambiguous
                    type: https://api.bitnob.com/errors/VALIDATION_FAILED
                sender_profile_incomplete:
                  summary: >-
                    An identity change that resubmits the profile leaves
                    required fields missing
                  value:
                    code: VALIDATION_FAILED
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      The sender profile is missing required fields: gender,
                      id_issue_date, document.
                    extensions:
                      error_code: SENDER_PROFILE_INCOMPLETE
                      missing_fields:
                        - gender
                        - id_issue_date
                        - document
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 422
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Sender Details Incomplete
                    type: https://api.bitnob.com/errors/VALIDATION_FAILED
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Required fields or the document are missing
            (SENDER_PROFILE_INCOMPLETE, missing_fields is an array), or
            customer_type is not exactly individual or business
            (CUSTOMER_TYPE_AMBIGUOUS). error_code is in extensions.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    Envelope:
      description: >-
        Successful responses are wrapped in this envelope, and so are errors a
        handler answers itself (request body and field validation, some
        not-found and conflict cases, ORG_NOT_ACTIVE): success is false and
        error carries a code and message. Errors raised by authentication and by
        the services behind a handler are a Problem instead.
      properties:
        data:
          description: >-
            The payload; its shape is given per operation. Omitted when there is
            none.
        error:
          $ref: '#/components/schemas/ErrorInfo'
        message:
          description: Human-readable summary; omitted when empty.
          type: string
        request_id:
          description: >-
            Set on error envelopes: the request's correlation id (req_ followed
            by a UUID), the same value as the X-Correlation-ID response header.
            Quote it to support.
          type: string
        success:
          description: true on success
          type: boolean
        timestamp:
          description: When the response was written.
          format: date-time
          type: string
      required:
        - success
        - timestamp
      type: object
    CustomersCustomer:
      properties:
        business_type:
          type: string
        card_counts:
          description: >-
            Null on create and update responses, or when counts could not be
            read.
          oneOf:
            - $ref: '#/components/schemas/CustomersCardCounts'
            - type: 'null'
        card_program_kyc:
          description: >-
            Present on get and list only; empty when no card-program KYC is on
            record.
          items:
            $ref: '#/components/schemas/CustomersCardProgramKYC'
          type: array
        city:
          description: City.
          type: string
        company_id:
          format: uuid
          type: string
        company_name:
          description: Company name.
          type: string
        country:
          description: Country.
          type: string
        country_of_birth:
          description: SWIFT sender profile, ISO 3166-1 alpha-3.
          type: string
        created_at:
          format: date-time
          type: string
        created_by:
          format: uuid
          type: string
        customer_type:
          description: Type of customer.
          example: individual
          type: string
        date_of_birth:
          description: Date of birth, YYYY-MM-DD.
          format: date
          type: string
        dial_code:
          description: International dial code, for example +234.
          type: string
        email:
          description: Email address.
          format: email
          type: string
        first_name:
          description: First name.
          type: string
        gender:
          description: SWIFT sender profile.
          type: string
        id:
          format: uuid
          type: string
        id_expiry_date:
          format: date
          type: string
        id_issue_date:
          format: date
          type: string
        id_number:
          description: Number on the identity document.
          type: string
        id_type:
          description: Type of identity document.
          type: string
        is_active:
          type: boolean
        kyc_status:
          description: Empty when nothing has been submitted.
          type: string
        last_name:
          description: Last name.
          type: string
        line1:
          description: Address line 1.
          type: string
        metadata:
          description: Always an empty string.
          type: string
        nationality:
          description: SWIFT sender profile, ISO 3166-1 alpha-3.
          type: string
        phone_number:
          description: Phone number without the dial code.
          type: string
        postal_code:
          description: Postal code.
          type: string
        registration_expiry_date:
          format: date
          type: string
        registration_issue_date:
          format: date
          type: string
        registration_number:
          description: Company registration number.
          type: string
        registration_type:
          type: string
        sender:
          anyOf:
            - $ref: '#/components/schemas/CustomersSender'
            - $ref: '#/components/schemas/CustomersSenderSummary'
          description: >-
            The SWIFT sender block. Full on a single-customer read, update and
            verify; state, version and expires_at on list rows.
        state:
          description: State.
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - company_id
        - email
        - customer_type
        - metadata
        - is_active
        - kyc_status
        - card_counts
        - created_by
        - created_at
        - updated_at
      type: object
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - properties:
            success:
              const: false
          required:
            - error
          type: object
      description: >-
        The envelope as an error: success is false, error is set, data is
        absent.
    Problem:
      description: >-
        RFC 7807 problem. Returned when authentication fails and for errors
        raised by the services behind a handler (validation, domain refusals
        such as FEATURE_NOT_ENABLED or PRECONDITION_FAILED, partner outages);
        branch on code.
      properties:
        code:
          description: >-
            Machine-readable; branch on this, not on the status or the wording.
            For example VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN,
            FEATURE_NOT_ENABLED, PERSONAL_WORKSPACE_CUSTOMERS,
            TIER_PRODUCT_LOCKED, NOT_FOUND, DUPLICATE_KEY_ERROR, ALREADY_EXISTS,
            PRECONDITION_FAILED, INSUFFICIENT_FUNDS, TIER_LIMIT_REACHED,
            RATE_LIMIT_EXCEEDED, TIMEOUT, SERVICE_UNAVAILABLE,
            LIMITS_UNAVAILABLE, PLATFORM_PAUSED, INTERNAL_ERROR.
          type: string
        correlation_id:
          description: >-
            The request's correlation id, the same value as the X-Correlation-ID
            response header.
          type: string
        detail:
          description: >-
            What went wrong for this request, safe to show; internal and partner
            failures carry a generic sentence.
          type: string
        extensions:
          additionalProperties: true
          description: >-
            Code-specific facts, for example feature_key (FEATURE_NOT_ENABLED),
            field or field_violations (VALIDATION_ERROR), rail, window, limit,
            used, requested and remaining (TIER_LIMIT_REACHED), scope
            (PLATFORM_PAUSED).
          type: object
        instance:
          type: string
        request_id:
          description: Equal to correlation_id.
          type: string
        status:
          description: The HTTP status, repeated.
          type: integer
        timestamp:
          format: date-time
          type: string
        title:
          description: >-
            Short summary of the code, for example Validation Error or Feature
            Not Enabled.
          type: string
        type:
          description: https://api.bitnob.com/errors/{code}
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - code
        - timestamp
      type: object
    ErrorInfo:
      properties:
        code:
          description: >-
            Machine-readable, for example BAD_REQUEST, NOT_FOUND, CONFLICT,
            ORG_NOT_ACTIVE, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE,
            INTERNAL_ERROR.
          type: string
        details:
          additionalProperties: true
          description: >-
            For field validation, a map of field name to message ("email":
            "Email must be a valid email address"); for a body that does not
            decode, the offending field.
          type: object
        message:
          type: string
      required:
        - message
      type: object
    CustomersCardCounts:
      description: >-
        Cards held by the customer, by status and type. Terminated is outside
        total.
      properties:
        active:
          format: int32
          type: integer
        blocked:
          format: int32
          type: integer
        frozen:
          format: int32
          type: integer
        lite:
          format: int32
          type: integer
        pending:
          format: int32
          type: integer
        pending_termination:
          format: int32
          type: integer
        prepaid_standard:
          format: int32
          type: integer
        standard:
          format: int32
          type: integer
        terminated:
          format: int32
          type: integer
        total:
          format: int32
          type: integer
      type: object
    CustomersCardProgramKYC:
      properties:
        card_program:
          description: Card program; see Cards for what each one is.
          enum:
            - prepaid
            - collateral
            - collateral_business
            - prepaid_platinum
            - prepaid_premium
          example: collateral
          type: string
        normalized_status:
          description: >-
            Normalised KYC status, for example none, initiated, pending,
            approved, rejected, expired, rejected_incomplete.
          example: approved
          type: string
      type: object
    CustomersSender:
      description: >-
        The customer's SWIFT sender state. Never carries the document key or a
        URL.
      properties:
        approved_version:
          description: The highest approved version, which payouts send as.
          type:
            - integer
            - 'null'
        decided_at:
          format: date-time
          type:
            - string
            - 'null'
        document:
          description: >-
            The first of documents (the primary document), kept for clients of
            the one-document shape; null when there is none.
          oneOf:
            - $ref: '#/components/schemas/CustomersSenderDocument'
            - type: 'null'
        documents:
          description: >-
            Every document, in order; the first is the primary document, sent to
            our partner as the proof of identity. Empty when there is none.
          items:
            $ref: '#/components/schemas/CustomersSenderDocument'
          maxItems: 5
          type: array
        expires_at:
          description: When the approved version expires.
          format: date
          type:
            - string
            - 'null'
        missing_fields:
          description: >-
            What the profile still lacks to be submitted; the document is
            document.
          items:
            type: string
          type: array
        rejection:
          description: Set when state is rejected.
          oneOf:
            - properties:
                hint:
                  type: string
                reason_code:
                  enum:
                    - DOCUMENT_UNREADABLE
                    - NAME_MISMATCH
                    - ID_EXPIRED
                    - DOCUMENT_TYPE_WRONG
                    - OTHER
                  type: string
              type: object
            - type: 'null'
        sender_type:
          description: >-
            individual or business, from customer_type; null when customer_type
            is not exactly one of them.
          oneOf:
            - enum:
                - individual
                - business
              type: string
            - type: 'null'
        state:
          $ref: '#/components/schemas/CustomersSenderState'
        submitted_at:
          format: date-time
          type:
            - string
            - 'null'
        updated_at:
          description: >-
            The customer row's updated_at, sent back on review decisions for the
            conflict check.
          format: date-time
          type: string
        version:
          description: The working version.
          type: integer
      required:
        - sender_type
        - state
        - version
        - approved_version
        - submitted_at
        - decided_at
        - rejection
        - expires_at
        - document
        - documents
        - missing_fields
        - updated_at
      type: object
    CustomersSenderSummary:
      description: The sender state on a list row.
      properties:
        expires_at:
          format: date
          type:
            - string
            - 'null'
        state:
          $ref: '#/components/schemas/CustomersSenderState'
        version:
          type: integer
      required:
        - state
        - version
        - expires_at
      type: object
    CustomersSenderDocument:
      description: One sender document. Never carries the key or a URL.
      properties:
        content_type:
          type: string
        id:
          description: Keeps the document on a later PUT ({"id":...} in documents).
          format: uuid
          type: string
        kind:
          description: >-
            sender_id (individual) or business_registration (business) for the
            first document, supporting for the rest.
          enum:
            - sender_id
            - business_registration
            - supporting
          type: string
        name:
          description: >-
            The name given on upload, else proofOfIdentity for the first
            document and supportingDocument{n} for the rest.
          type: string
        size_bytes:
          type: integer
        uploaded_at:
          format: date-time
          type:
            - string
            - 'null'
      type: object
    CustomersSenderState:
      enum:
        - not_submitted
        - pending
        - approved
        - rejected
        - expired
      type: string
  headers:
    X-Correlation-ID:
      description: >-
        Generated for every request (any value the client sends is ignored);
        quote it to support. Errors repeat it as request_id and correlation_id.
      example: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      example: 1
      schema:
        minimum: 0
        type: integer
  responses:
    Unauthorized:
      content:
        application/json:
          examples:
            unauthorized_auth_failed:
              $ref: '#/components/examples/UnauthorizedAuthFailed'
            unauthorized_invalid_secret:
              $ref: '#/components/examples/UnauthorizedInvalidSecret'
            unauthorized_invalid_signature:
              $ref: '#/components/examples/UnauthorizedInvalidSignature'
            unauthorized_locked_out:
              $ref: '#/components/examples/UnauthorizedLockedOut'
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        Authentication failed: a signing header is missing or malformed, the
        timestamp is more than 5 minutes off, the signature or secret is wrong,
        or the client is locked out after failed checks (UNAUTHORIZED).
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    RequestTimeout:
      content:
        application/json:
          examples:
            request_timeout:
              $ref: '#/components/examples/RequestTimeout'
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        The request ran past its deadline (TIMEOUT); retry, with the same
        reference for writes.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    TooManyRequests:
      content:
        application/json:
          examples:
            rate_limited:
              $ref: '#/components/examples/RateLimited'
            rate_limited_envelope:
              $ref: '#/components/examples/RateLimitedEnvelope'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Rate limited. The per-IP limiter (500 requests a minute) answers with a
        Problem and Retry-After; operation-specific throttles answer with the
        envelope.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    ServerError:
      content:
        application/json:
          examples:
            internal_error:
              $ref: '#/components/examples/InternalError'
            internal_error_envelope:
              $ref: '#/components/examples/InternalErrorEnvelope'
            internal_error_unhandled:
              $ref: '#/components/examples/InternalErrorUnhandled'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Something failed on our side; safe to retry idempotent requests
        (INTERNAL_ERROR).
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    ServiceUnavailable:
      content:
        application/json:
          examples:
            auth_service_busy:
              $ref: '#/components/examples/AuthServiceBusy'
            auth_service_unavailable:
              $ref: '#/components/examples/AuthServiceUnavailable'
            limits_unavailable:
              $ref: '#/components/examples/LimitsUnavailable'
            partner_unavailable:
              $ref: '#/components/examples/PartnerUnavailable'
            platform_paused:
              $ref: '#/components/examples/PlatformPaused'
            service_unavailable_envelope:
              $ref: '#/components/examples/ServiceUnavailableEnvelope'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Temporarily unavailable; retry later. The identity service could not
        check the credentials (sent with Retry-After), a partner is down
        (SERVICE_UNAVAILABLE), the limits check could not run
        (LIMITS_UNAVAILABLE), or a platform control paused money movement
        (PLATFORM_PAUSED).
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
  examples:
    ClientInactive:
      summary: The API key's client is deactivated
      value:
        code: FORBIDDEN
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Client account is inactive
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Forbidden
        type: https://api.bitnob.com/errors/FORBIDDEN
    IPNotWhitelisted:
      summary: The request came from an IP not on the key's allowlist
      value:
        code: FORBIDDEN
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: IP address not whitelisted
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Forbidden
        type: https://api.bitnob.com/errors/FORBIDDEN
    OrgNotActiveLive:
      description: Sandbox keys are never refused this way.
      summary: A live key on an organisation that is not active yet
      value:
        error:
          code: ORG_NOT_ACTIVE
          message: >-
            Your business isn't active yet, so live isn't available. Use your
            sandbox keys until it's activated.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    UnauthorizedAuthFailed:
      description: >-
        Returned when X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce or
        X-Auth-Signature is missing, the nonce is not 8 to 128 characters, the
        signature is not hex, or the timestamp is more than 5 minutes from the
        server's clock. The detail does not say which; check each.
      summary: A signing header is missing or malformed, or the timestamp is stale
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Authentication failed
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedInvalidSecret:
      summary: 'Secret mode: the client id or secret is wrong'
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Invalid credentials
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedInvalidSignature:
      description: >-
        The detail is the identity service's reason when it gives one (an
        unknown client or a reused nonce reads differently); Invalid signature
        otherwise.
      summary: The signature does not match
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Invalid signature
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedLockedOut:
      summary: Too many failed credential checks
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Too many failed credential checks; retry later
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    RequestTimeout:
      summary: The request ran past its deadline
      value:
        code: TIMEOUT
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: The request took too long to complete. Please try again.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 408
        timestamp: '2026-10-30T09:15:02Z'
        title: Request Timeout
        type: https://api.bitnob.com/errors/TIMEOUT
    RateLimited:
      summary: The per-IP limit (500 requests a minute) is reached
      value:
        code: RATE_LIMIT_EXCEEDED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Too many requests. Please try again later.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 429
        timestamp: '2026-10-30T09:15:02Z'
        title: Rate Limit Exceeded
        type: https://api.bitnob.com/errors/RATE_LIMIT_EXCEEDED
    RateLimitedEnvelope:
      summary: An operation-specific throttle (answered by the handler)
      value:
        error:
          code: RATE_LIMIT_EXCEEDED
          message: >-
            a verification link was sent to this customer in the last minute;
            try again shortly
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    InternalError:
      summary: Something failed on our side
      value:
        code: INTERNAL_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: An internal error occurred. Please try again later.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 500
        timestamp: '2026-10-30T09:15:02Z'
        title: Internal Server Error
        type: https://api.bitnob.com/errors/INTERNAL_ERROR
    InternalErrorEnvelope:
      summary: A failure answered by the handler
      value:
        error:
          code: INTERNAL_ERROR
          message: Failed to list transactions
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    InternalErrorUnhandled:
      summary: An unexpected failure
      value:
        code: INTERNAL_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: An internal server error occurred
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 500
        timestamp: '2026-10-30T09:15:02Z'
        title: Internal Server Error
        type: https://api.bitnob.com/errors/INTERNAL_ERROR
    AuthServiceBusy:
      description: 'Sent with Retry-After: 1.'
      summary: Too many large signed bodies are being checked at once
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Authentication service is busy, retry shortly
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    AuthServiceUnavailable:
      description: 'Sent with Retry-After: 1. The detail is worded exactly like this today.'
      summary: The identity service could not be reached to check the credentials
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Service Authentication service unavailable is currently unavailable
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    LimitsUnavailable:
      summary: The tier limit check could not run
      value:
        code: LIMITS_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          We could not verify your account limits right now. Please try again
          shortly.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Limits Unavailable
        type: https://api.bitnob.com/errors/LIMITS_UNAVAILABLE
    PartnerUnavailable:
      summary: A partner or internal service is unavailable
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Service is temporarily unavailable. Please try again later.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    PlatformPaused:
      summary: Money movement is paused by a platform control
      value:
        code: PLATFORM_PAUSED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          Money movement is temporarily paused. Nothing is lost — requests can
          be retried once the pause lifts.
        extensions:
          scope: asset:BTC
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Money Movement Paused
        type: https://api.bitnob.com/errors/PLATFORM_PAUSED
    ServiceUnavailableEnvelope:
      summary: Unavailable (answered by the handler)
      value:
        error:
          code: SERVICE_UNAVAILABLE
          message: LNURL payments are temporarily disabled
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
  securitySchemes:
    BitnobClientId:
      type: apiKey
      in: header
      name: X-Auth-Client
      description: |
        Your workspace client id.
    BitnobClientSecret:
      type: apiKey
      in: header
      name: X-Auth-Secret
      description: >
        Your sandbox client secret. The playground accepts sandbox keys only,
        sends the secret straight from your browser to the API, and needs your
        IP on the key's whitelist. In your own integration, sign requests with
        HMAC instead of sending the secret.

````

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