openapi: 3.1.0
info:
  title: Increase API
  description: >-
    Increase is a bank-grade payments and financial infrastructure platform that
    exposes a single REST API for moving and holding money in the United States.
    This document models the primary resources of the Increase API - Accounts,
    Account Numbers, Cards, Card Payments, ACH / Wire / Real-Time Payments / Check
    transfers, Transactions, Entities, Events and webhooks, Bookkeeping, Card
    Profiles and Digital Wallets, Lockboxes, and Simulations. It is grounded in
    Increase's public OpenAPI 3.1 spec (https://api.increase.com/openapi.json) and
    the Stainless-generated SDKs. Authentication is a Bearer API key. All endpoints
    are HTTPS REST; state changes are delivered as Events over HTTP webhooks (no
    WebSocket surface). Requests support idempotency via the `Idempotency-Key`
    header. This is a representative, not exhaustive, subset of the full API.
  version: '0.0.1'
  contact:
    name: Increase
    url: https://increase.com
  license:
    name: Increase Documentation
    url: https://increase.com/documentation
servers:
  - url: https://api.increase.com
    description: Production
  - url: https://sandbox.increase.com
    description: Sandbox
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Deposit accounts held at Increase partner banks.
  - name: Account Numbers
    description: Routing and account number pairs that can receive funds.
  - name: External Accounts
    description: Counterparty bank accounts you send to or debit.
  - name: Cards
    description: Virtual and physical commercial cards.
  - name: Card Payments
    description: Card authorization and settlement lifecycle.
  - name: ACH Transfers
    description: FedACH credit and debit transfers, inbound and outbound.
  - name: Wire Transfers
    description: Fedwire transfers and drawdown requests.
  - name: Real-Time Payments
    description: Instant RTP transfers, inbound and outbound.
  - name: Check Transfers
    description: Printed and mailed checks and check deposits.
  - name: Transactions
    description: Settled, pending, and declined ledger transactions.
  - name: Entities
    description: KYC/KYB entities that own accounts.
  - name: Events
    description: Events and webhook Event Subscriptions.
  - name: Bookkeeping
    description: Double-entry sub-ledger built on Increase money movement.
  - name: Card Profiles
    description: Digital and physical card profiles and wallet tokens.
  - name: Lockboxes
    description: Physical lockbox addresses and inbound mail.
  - name: Simulations
    description: Sandbox-only endpoints for deterministic testing.
paths:
  /accounts:
    get:
      operationId: listAccounts
      tags: [Accounts]
      summary: List Accounts
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/AccountList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccount
      tags: [Accounts]
      summary: Create an Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                entity_id: { type: string }
                program_id: { type: string }
                informational_entity_id: { type: string }
      responses:
        '200':
          $ref: '#/components/responses/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /accounts/{account_id}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: retrieveAccount
      tags: [Accounts]
      summary: Retrieve an Account
      responses:
        '200':
          $ref: '#/components/responses/Account'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAccount
      tags: [Accounts]
      summary: Update an Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
      responses:
        '200':
          $ref: '#/components/responses/Account'
  /accounts/{account_id}/balance:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: retrieveAccountBalance
      tags: [Accounts]
      summary: Retrieve an Account Balance
      responses:
        '200':
          description: Account balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_balance: { type: integer }
                  available_balance: { type: integer }
  /accounts/{account_id}/close:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    post:
      operationId: closeAccount
      tags: [Accounts]
      summary: Close an Account
      responses:
        '200':
          $ref: '#/components/responses/Account'
  /account_numbers:
    get:
      operationId: listAccountNumbers
      tags: [Account Numbers]
      summary: List Account Numbers
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of Account Numbers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumberList'
    post:
      operationId: createAccountNumber
      tags: [Account Numbers]
      summary: Create an Account Number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, name]
              properties:
                account_id: { type: string }
                name: { type: string }
      responses:
        '200':
          description: The created Account Number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumber'
  /account_numbers/{account_number_id}:
    parameters:
      - name: account_number_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveAccountNumber
      tags: [Account Numbers]
      summary: Retrieve an Account Number
      responses:
        '200':
          description: The Account Number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumber'
    patch:
      operationId: updateAccountNumber
      tags: [Account Numbers]
      summary: Update an Account Number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                status: { type: string, enum: [active, disabled, canceled] }
      responses:
        '200':
          description: The updated Account Number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumber'
  /external_accounts:
    get:
      operationId: listExternalAccounts
      tags: [External Accounts]
      summary: List External Accounts
      responses:
        '200':
          description: A list of External Accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/ExternalAccount' }
    post:
      operationId: createExternalAccount
      tags: [External Accounts]
      summary: Create an External Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [routing_number, account_number, description]
              properties:
                routing_number: { type: string }
                account_number: { type: string }
                description: { type: string }
                funding: { type: string, enum: [checking, savings, other] }
      responses:
        '200':
          description: The created External Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
  /external_accounts/{external_account_id}:
    parameters:
      - name: external_account_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveExternalAccount
      tags: [External Accounts]
      summary: Retrieve an External Account
      responses:
        '200':
          description: The External Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
    patch:
      operationId: updateExternalAccount
      tags: [External Accounts]
      summary: Update an External Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description: { type: string }
                status: { type: string, enum: [active, archived] }
      responses:
        '200':
          description: The updated External Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
  /routing_numbers:
    get:
      operationId: listRoutingNumbers
      tags: [External Accounts]
      summary: List Routing Numbers
      description: Look up which real-time payment rails a given routing number supports.
      parameters:
        - name: routing_number
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Routing number details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
  /cards:
    get:
      operationId: listCards
      tags: [Cards]
      summary: List Cards
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of Cards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Card' }
    post:
      operationId: createCard
      tags: [Cards]
      summary: Create a Card
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id]
              properties:
                account_id: { type: string }
                description: { type: string }
                entity_id: { type: string }
      responses:
        '200':
          description: The created Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/{card_id}:
    parameters:
      - name: card_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveCard
      tags: [Cards]
      summary: Retrieve a Card
      responses:
        '200':
          description: The Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
    patch:
      operationId: updateCard
      tags: [Cards]
      summary: Update a Card
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description: { type: string }
                status: { type: string, enum: [active, disabled, canceled] }
      responses:
        '200':
          description: The updated Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/{card_id}/details:
    parameters:
      - name: card_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveCardDetails
      tags: [Cards]
      summary: Retrieve sensitive Card details
      description: Returns the PAN, expiration, and CVC for a Card. Restricted; typically retrieved via a secure iframe.
      responses:
        '200':
          description: Sensitive card details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  card_id: { type: string }
                  primary_account_number: { type: string }
                  expiration_month: { type: integer }
                  expiration_year: { type: integer }
                  verification_code: { type: string }
  /card_payments:
    get:
      operationId: listCardPayments
      tags: [Card Payments]
      summary: List Card Payments
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of Card Payments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/CardPayment' }
  /card_payments/{card_payment_id}:
    parameters:
      - name: card_payment_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveCardPayment
      tags: [Card Payments]
      summary: Retrieve a Card Payment
      responses:
        '200':
          description: The Card Payment with its full element timeline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardPayment'
  /card_disputes:
    get:
      operationId: listCardDisputes
      tags: [Card Payments]
      summary: List Card Disputes
      responses:
        '200':
          description: A list of Card Disputes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
    post:
      operationId: createCardDispute
      tags: [Card Payments]
      summary: Create a Card Dispute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [disputed_transaction_id, explanation]
              properties:
                disputed_transaction_id: { type: string }
                explanation: { type: string }
      responses:
        '200':
          description: The created Card Dispute.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /real_time_decisions/{real_time_decision_id}:
    parameters:
      - name: real_time_decision_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveRealTimeDecision
      tags: [Card Payments]
      summary: Retrieve a Real-Time Decision
      responses:
        '200':
          description: The Real-Time Decision awaiting your action.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /real_time_decisions/{real_time_decision_id}/action:
    parameters:
      - name: real_time_decision_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: actionRealTimeDecision
      tags: [Card Payments]
      summary: Action a Real-Time Decision
      description: Approve or decline a card authorization, digital wallet token provisioning, or digital wallet authentication in real time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated Real-Time Decision.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /ach_transfers:
    get:
      operationId: listACHTransfers
      tags: [ACH Transfers]
      summary: List ACH Transfers
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of ACH Transfers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/ACHTransfer' }
    post:
      operationId: createACHTransfer
      tags: [ACH Transfers]
      summary: Create an ACH Transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, amount, statement_descriptor]
              properties:
                account_id: { type: string }
                amount: { type: integer, description: Cents. Positive credits the destination, negative debits it. }
                statement_descriptor: { type: string }
                account_number: { type: string }
                routing_number: { type: string }
                external_account_id: { type: string }
                funding: { type: string, enum: [checking, savings] }
      responses:
        '200':
          description: The created ACH Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHTransfer'
  /ach_transfers/{ach_transfer_id}:
    parameters:
      - name: ach_transfer_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveACHTransfer
      tags: [ACH Transfers]
      summary: Retrieve an ACH Transfer
      responses:
        '200':
          description: The ACH Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHTransfer'
  /ach_transfers/{ach_transfer_id}/approve:
    parameters:
      - name: ach_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: approveACHTransfer
      tags: [ACH Transfers]
      summary: Approve an ACH Transfer
      responses:
        '200':
          description: The approved ACH Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHTransfer'
  /ach_transfers/{ach_transfer_id}/cancel:
    parameters:
      - name: ach_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: cancelACHTransfer
      tags: [ACH Transfers]
      summary: Cancel a pending ACH Transfer
      responses:
        '200':
          description: The canceled ACH Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHTransfer'
  /inbound_ach_transfers/{inbound_ach_transfer_id}/decline:
    parameters:
      - name: inbound_ach_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: declineInboundACHTransfer
      tags: [ACH Transfers]
      summary: Decline an Inbound ACH Transfer
      responses:
        '200':
          description: The declined Inbound ACH Transfer.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /ach_prenotifications:
    post:
      operationId: createACHPrenotification
      tags: [ACH Transfers]
      summary: Create an ACH Prenotification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, account_number, routing_number]
              properties:
                account_id: { type: string }
                account_number: { type: string }
                routing_number: { type: string }
      responses:
        '200':
          description: The created ACH Prenotification.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /wire_transfers:
    get:
      operationId: listWireTransfers
      tags: [Wire Transfers]
      summary: List Wire Transfers
      responses:
        '200':
          description: A list of Wire Transfers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/WireTransfer' }
    post:
      operationId: createWireTransfer
      tags: [Wire Transfers]
      summary: Create a Wire Transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, amount, message_to_recipient]
              properties:
                account_id: { type: string }
                amount: { type: integer }
                message_to_recipient: { type: string }
                beneficiary_name: { type: string }
                account_number: { type: string }
                routing_number: { type: string }
                external_account_id: { type: string }
      responses:
        '200':
          description: The created Wire Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WireTransfer'
  /wire_transfers/{wire_transfer_id}:
    parameters:
      - name: wire_transfer_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveWireTransfer
      tags: [Wire Transfers]
      summary: Retrieve a Wire Transfer
      responses:
        '200':
          description: The Wire Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WireTransfer'
  /wire_transfers/{wire_transfer_id}/approve:
    parameters:
      - name: wire_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: approveWireTransfer
      tags: [Wire Transfers]
      summary: Approve a Wire Transfer
      responses:
        '200':
          description: The approved Wire Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WireTransfer'
  /wire_transfers/{wire_transfer_id}/cancel:
    parameters:
      - name: wire_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: cancelWireTransfer
      tags: [Wire Transfers]
      summary: Cancel a pending Wire Transfer
      responses:
        '200':
          description: The canceled Wire Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WireTransfer'
  /wire_drawdown_requests:
    post:
      operationId: createWireDrawdownRequest
      tags: [Wire Transfers]
      summary: Create a Wire Drawdown Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_number_id, amount, recipient_account_number, recipient_routing_number]
              properties:
                account_number_id: { type: string }
                amount: { type: integer }
                recipient_account_number: { type: string }
                recipient_routing_number: { type: string }
                recipient_name: { type: string }
      responses:
        '200':
          description: The created Wire Drawdown Request.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /real_time_payments_transfers:
    get:
      operationId: listRealTimePaymentsTransfers
      tags: [Real-Time Payments]
      summary: List Real-Time Payments Transfers
      responses:
        '200':
          description: A list of Real-Time Payments Transfers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/RealTimePaymentsTransfer' }
    post:
      operationId: createRealTimePaymentsTransfer
      tags: [Real-Time Payments]
      summary: Create a Real-Time Payments Transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source_account_number_id, amount, creditor_name, remittance_information]
              properties:
                source_account_number_id: { type: string }
                amount: { type: integer }
                creditor_name: { type: string }
                remittance_information: { type: string }
                destination_account_number: { type: string }
                destination_routing_number: { type: string }
                external_account_id: { type: string }
      responses:
        '200':
          description: The created Real-Time Payments Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealTimePaymentsTransfer'
  /real_time_payments_transfers/{real_time_payments_transfer_id}:
    parameters:
      - name: real_time_payments_transfer_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveRealTimePaymentsTransfer
      tags: [Real-Time Payments]
      summary: Retrieve a Real-Time Payments Transfer
      responses:
        '200':
          description: The Real-Time Payments Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealTimePaymentsTransfer'
  /inbound_real_time_payments_transfers/{inbound_real_time_payments_transfer_id}:
    parameters:
      - name: inbound_real_time_payments_transfer_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveInboundRealTimePaymentsTransfer
      tags: [Real-Time Payments]
      summary: Retrieve an Inbound Real-Time Payments Transfer
      responses:
        '200':
          description: The Inbound Real-Time Payments Transfer.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /check_transfers:
    get:
      operationId: listCheckTransfers
      tags: [Check Transfers]
      summary: List Check Transfers
      responses:
        '200':
          description: A list of Check Transfers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/CheckTransfer' }
    post:
      operationId: createCheckTransfer
      tags: [Check Transfers]
      summary: Create a Check Transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, amount]
              properties:
                account_id: { type: string }
                amount: { type: integer }
                source_account_number_id: { type: string }
                fulfillment_method: { type: string, enum: [physical_check, third_party] }
      responses:
        '200':
          description: The created Check Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckTransfer'
  /check_transfers/{check_transfer_id}:
    parameters:
      - name: check_transfer_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveCheckTransfer
      tags: [Check Transfers]
      summary: Retrieve a Check Transfer
      responses:
        '200':
          description: The Check Transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckTransfer'
  /check_transfers/{check_transfer_id}/stop_payment:
    parameters:
      - name: check_transfer_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: stopPaymentCheckTransfer
      tags: [Check Transfers]
      summary: Stop payment on a Check Transfer
      responses:
        '200':
          description: The Check Transfer with a stop payment applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckTransfer'
  /check_deposits:
    get:
      operationId: listCheckDeposits
      tags: [Check Transfers]
      summary: List Check Deposits
      responses:
        '200':
          description: A list of Check Deposits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
    post:
      operationId: createCheckDeposit
      tags: [Check Transfers]
      summary: Create a Check Deposit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, amount, front_image_file_id, back_image_file_id]
              properties:
                account_id: { type: string }
                amount: { type: integer }
                front_image_file_id: { type: string }
                back_image_file_id: { type: string }
      responses:
        '200':
          description: The created Check Deposit.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /transactions:
    get:
      operationId: listTransactions
      tags: [Transactions]
      summary: List Transactions
      parameters:
        - name: account_id
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of Transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Transaction' }
  /transactions/{transaction_id}:
    parameters:
      - name: transaction_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveTransaction
      tags: [Transactions]
      summary: Retrieve a Transaction
      responses:
        '200':
          description: The Transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
  /pending_transactions:
    get:
      operationId: listPendingTransactions
      tags: [Transactions]
      summary: List Pending Transactions
      responses:
        '200':
          description: A list of Pending Transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
  /declined_transactions/{declined_transaction_id}:
    parameters:
      - name: declined_transaction_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveDeclinedTransaction
      tags: [Transactions]
      summary: Retrieve a Declined Transaction
      responses:
        '200':
          description: The Declined Transaction.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /entities:
    get:
      operationId: listEntities
      tags: [Entities]
      summary: List Entities
      responses:
        '200':
          description: A list of Entities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Entity' }
    post:
      operationId: createEntity
      tags: [Entities]
      summary: Create an Entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [structure]
              properties:
                structure: { type: string, enum: [corporation, natural_person, joint, trust, government_authority] }
                natural_person: { type: object, additionalProperties: true }
                corporation: { type: object, additionalProperties: true }
      responses:
        '200':
          description: The created Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
  /entities/{entity_id}:
    parameters:
      - name: entity_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveEntity
      tags: [Entities]
      summary: Retrieve an Entity
      responses:
        '200':
          description: The Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
  /entities/{entity_id}/archive:
    parameters:
      - name: entity_id
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: archiveEntity
      tags: [Entities]
      summary: Archive an Entity
      responses:
        '200':
          description: The archived Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
  /entity_supplemental_documents:
    post:
      operationId: createSupplementalDocument
      tags: [Entities]
      summary: Create a supplemental document for an Entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [entity_id, file_id]
              properties:
                entity_id: { type: string }
                file_id: { type: string }
      responses:
        '200':
          description: The created supplemental document.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /events:
    get:
      operationId: listEvents
      tags: [Events]
      summary: List Events
      description: Poll or backfill the Events emitted by state changes across every resource. Retains up to 30 days of history.
      parameters:
        - name: category
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of Events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Event' }
  /events/{event_id}:
    parameters:
      - name: event_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveEvent
      tags: [Events]
      summary: Retrieve an Event
      responses:
        '200':
          description: The Event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /event_subscriptions:
    get:
      operationId: listEventSubscriptions
      tags: [Events]
      summary: List Event Subscriptions
      responses:
        '200':
          description: A list of Event Subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/EventSubscription' }
    post:
      operationId: createEventSubscription
      tags: [Events]
      summary: Create an Event Subscription
      description: Register an HTTPS endpoint to receive signed webhooks for Events, optionally filtered to a category.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri }
                shared_secret: { type: string }
                selected_event_category: { type: string }
      responses:
        '200':
          description: The created Event Subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
  /event_subscriptions/{event_subscription_id}:
    parameters:
      - name: event_subscription_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveEventSubscription
      tags: [Events]
      summary: Retrieve an Event Subscription
      responses:
        '200':
          description: The Event Subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
    patch:
      operationId: updateEventSubscription
      tags: [Events]
      summary: Update an Event Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [active, disabled, deleted] }
      responses:
        '200':
          description: The updated Event Subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
  /bookkeeping_accounts:
    get:
      operationId: listBookkeepingAccounts
      tags: [Bookkeeping]
      summary: List Bookkeeping Accounts
      responses:
        '200':
          description: A list of Bookkeeping Accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/BookkeepingAccount' }
    post:
      operationId: createBookkeepingAccount
      tags: [Bookkeeping]
      summary: Create a Bookkeeping Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                account_id: { type: string }
                entity_id: { type: string }
                compliance_category: { type: string, enum: [commingled_cash, customer_balance] }
      responses:
        '200':
          description: The created Bookkeeping Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookkeepingAccount'
  /bookkeeping_accounts/{bookkeeping_account_id}:
    parameters:
      - name: bookkeeping_account_id
        in: path
        required: true
        schema: { type: string }
    patch:
      operationId: updateBookkeepingAccount
      tags: [Bookkeeping]
      summary: Update a Bookkeeping Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
      responses:
        '200':
          description: The updated Bookkeeping Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookkeepingAccount'
  /bookkeeping_accounts/{bookkeeping_account_id}/balance:
    parameters:
      - name: bookkeeping_account_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveBookkeepingBalance
      tags: [Bookkeeping]
      summary: Retrieve a Bookkeeping Account Balance
      responses:
        '200':
          description: The Bookkeeping Account balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance: { type: integer }
  /bookkeeping_entry_sets:
    get:
      operationId: listBookkeepingEntrySets
      tags: [Bookkeeping]
      summary: List Bookkeeping Entry Sets
      responses:
        '200':
          description: A list of Bookkeeping Entry Sets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
    post:
      operationId: createBookkeepingEntrySet
      tags: [Bookkeeping]
      summary: Create a Bookkeeping Entry Set
      description: Post a balanced set of double-entry Bookkeeping Entries transactionally.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [entries]
              properties:
                date: { type: string, format: date-time }
                transaction_id: { type: string }
                entries:
                  type: array
                  items:
                    type: object
                    required: [account_id, amount]
                    properties:
                      account_id: { type: string }
                      amount: { type: integer }
      responses:
        '200':
          description: The created Bookkeeping Entry Set.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /bookkeeping_entries/{bookkeeping_entry_id}:
    parameters:
      - name: bookkeeping_entry_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveBookkeepingEntry
      tags: [Bookkeeping]
      summary: Retrieve a Bookkeeping Entry
      responses:
        '200':
          description: The Bookkeeping Entry.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /digital_card_profiles:
    get:
      operationId: listDigitalCardProfiles
      tags: [Card Profiles]
      summary: List Digital Card Profiles
      responses:
        '200':
          description: A list of Digital Card Profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
    post:
      operationId: createDigitalCardProfile
      tags: [Card Profiles]
      summary: Create a Digital Card Profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description, app_icon_file_id, card_description, issuer_name]
              properties:
                description: { type: string }
                app_icon_file_id: { type: string }
                card_description: { type: string }
                issuer_name: { type: string }
      responses:
        '200':
          description: The created Digital Card Profile.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /physical_card_profiles:
    get:
      operationId: listPhysicalCardProfiles
      tags: [Card Profiles]
      summary: List Physical Card Profiles
      responses:
        '200':
          description: A list of Physical Card Profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
  /digital_wallet_tokens:
    get:
      operationId: listDigitalWalletTokens
      tags: [Card Profiles]
      summary: List Digital Wallet Tokens
      responses:
        '200':
          description: A list of Digital Wallet Tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
  /digital_wallet_tokens/{digital_wallet_token_id}:
    parameters:
      - name: digital_wallet_token_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveDigitalWalletToken
      tags: [Card Profiles]
      summary: Retrieve a Digital Wallet Token
      responses:
        '200':
          description: The Digital Wallet Token.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /lockboxes:
    get:
      operationId: listLockboxes
      tags: [Lockboxes]
      summary: List Lockboxes
      responses:
        '200':
          description: A list of Lockboxes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object, additionalProperties: true }
    post:
      operationId: createLockbox
      tags: [Lockboxes]
      summary: Create a Lockbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id]
              properties:
                account_id: { type: string }
                description: { type: string }
                recipient_name: { type: string }
      responses:
        '200':
          description: The created Lockbox.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /lockboxes/{lockbox_id}:
    parameters:
      - name: lockbox_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveLockbox
      tags: [Lockboxes]
      summary: Retrieve a Lockbox
      responses:
        '200':
          description: The Lockbox.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    patch:
      operationId: updateLockbox
      tags: [Lockboxes]
      summary: Update a Lockbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description: { type: string }
                status: { type: string, enum: [active, inactive] }
      responses:
        '200':
          description: The updated Lockbox.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /inbound_mail_items/{inbound_mail_item_id}:
    parameters:
      - name: inbound_mail_item_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: retrieveInboundMailItem
      tags: [Lockboxes]
      summary: Retrieve an Inbound Mail Item
      responses:
        '200':
          description: The Inbound Mail Item scanned at a Lockbox.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /simulations/inbound_ach_transfers:
    post:
      operationId: simulateInboundACHTransfer
      tags: [Simulations]
      summary: Simulate an inbound ACH transfer
      description: Sandbox-only. Simulates money arriving at one of your Account Numbers over ACH.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_number_id, amount]
              properties:
                account_number_id: { type: string }
                amount: { type: integer }
      responses:
        '200':
          description: The simulated Inbound ACH Transfer.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /simulations/card_authorizations:
    post:
      operationId: simulateCardAuthorization
      tags: [Simulations]
      summary: Simulate a card authorization
      description: Sandbox-only. Simulates a merchant authorizing a Card, triggering any Real-Time Decision.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                card_id: { type: string }
                amount: { type: integer }
                merchant_descriptor: { type: string }
      responses:
        '200':
          description: The simulated card authorization result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /simulations/inbound_wire_transfers:
    post:
      operationId: simulateInboundWireTransfer
      tags: [Simulations]
      summary: Simulate an inbound wire transfer
      description: Sandbox-only. Simulates a Fedwire arriving at one of your Account Numbers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_number_id, amount]
              properties:
                account_number_id: { type: string }
                amount: { type: integer }
      responses:
        '200':
          description: The simulated Inbound Wire Transfer.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Increase API key passed as `Authorization: Bearer YOUR_API_KEY`. Keys are
        environment-scoped (production vs sandbox). OAuth is also supported for
        platform / Increase-for-platforms integrations.
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      description: Return the page of results starting after this cursor.
      schema: { type: string }
    Limit:
      name: limit
      in: query
      required: false
      description: Number of results to return per page (1-100, default 100).
      schema: { type: integer, default: 100, minimum: 1, maximum: 100 }
    AccountId:
      name: account_id
      in: path
      required: true
      description: The identifier of the Account.
      schema: { type: string }
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: The requested object was not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    ValidationError:
      description: The request failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Account:
      description: An Account.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Account' }
    AccountList:
      description: A list of Accounts.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items: { $ref: '#/components/schemas/Account' }
              next_cursor: { type: string, nullable: true }
  schemas:
    Error:
      type: object
      properties:
        type: { type: string }
        title: { type: string }
        detail: { type: string, nullable: true }
        status: { type: integer }
    Account:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        entity_id: { type: string, nullable: true }
        program_id: { type: string }
        currency: { type: string, example: USD }
        status: { type: string, enum: [open, closed] }
        bank: { type: string }
        created_at: { type: string, format: date-time }
        type: { type: string, example: account }
    AccountNumber:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        account_number: { type: string }
        routing_number: { type: string }
        name: { type: string }
        status: { type: string, enum: [active, disabled, canceled] }
        type: { type: string, example: account_number }
    AccountNumberList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AccountNumber' }
        next_cursor: { type: string, nullable: true }
    ExternalAccount:
      type: object
      properties:
        id: { type: string }
        routing_number: { type: string }
        account_number: { type: string }
        description: { type: string }
        funding: { type: string, enum: [checking, savings, other] }
        status: { type: string, enum: [active, archived] }
        type: { type: string, example: external_account }
    Card:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        description: { type: string, nullable: true }
        last4: { type: string }
        expiration_month: { type: integer }
        expiration_year: { type: integer }
        status: { type: string, enum: [active, disabled, canceled] }
        type: { type: string, example: card }
    CardPayment:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        card_id: { type: string }
        state: { type: object, additionalProperties: true }
        elements:
          type: array
          description: The ordered lifecycle events (authorization, settlement, refund, reversal, etc.).
          items: { type: object, additionalProperties: true }
        type: { type: string, example: card_payment }
    ACHTransfer:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        amount: { type: integer }
        currency: { type: string, example: USD }
        statement_descriptor: { type: string }
        status: { type: string, enum: [pending_approval, pending_submission, submitted, returned, rejected, canceled] }
        routing_number: { type: string, nullable: true }
        type: { type: string, example: ach_transfer }
    WireTransfer:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        amount: { type: integer }
        message_to_recipient: { type: string }
        beneficiary_name: { type: string, nullable: true }
        status: { type: string, enum: [pending_approval, pending_creating, submitted, complete, canceled, reversed] }
        type: { type: string, example: wire_transfer }
    RealTimePaymentsTransfer:
      type: object
      properties:
        id: { type: string }
        source_account_number_id: { type: string }
        amount: { type: integer }
        creditor_name: { type: string }
        remittance_information: { type: string }
        status: { type: string, enum: [pending_approval, pending_submission, submitted, complete, rejected, canceled] }
        type: { type: string, example: real_time_payments_transfer }
    CheckTransfer:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        amount: { type: integer }
        fulfillment_method: { type: string, enum: [physical_check, third_party] }
        status: { type: string, enum: [pending_approval, pending_submission, submitting, submitted, pending_mailing, mailed, deposited, stopped, returned, rejected, canceled] }
        type: { type: string, example: check_transfer }
    Transaction:
      type: object
      properties:
        id: { type: string }
        account_id: { type: string }
        amount: { type: integer }
        currency: { type: string, example: USD }
        description: { type: string }
        route_id: { type: string, nullable: true }
        source:
          type: object
          description: A typed object describing exactly what moved money.
          additionalProperties: true
        created_at: { type: string, format: date-time }
        type: { type: string, example: transaction }
    Entity:
      type: object
      properties:
        id: { type: string }
        structure: { type: string, enum: [corporation, natural_person, joint, trust, government_authority] }
        status: { type: string, enum: [active, archived, disabled] }
        description: { type: string, nullable: true }
        type: { type: string, example: entity }
    Event:
      type: object
      properties:
        id: { type: string }
        category: { type: string, description: e.g. transaction.created, ach_transfer.updated, account.created }
        associated_object_id: { type: string }
        associated_object_type: { type: string }
        created_at: { type: string, format: date-time }
        type: { type: string, example: event }
    EventSubscription:
      type: object
      properties:
        id: { type: string }
        url: { type: string, format: uri }
        status: { type: string, enum: [active, disabled, deleted, requires_attention] }
        selected_event_category: { type: string, nullable: true }
        type: { type: string, example: event_subscription }
    BookkeepingAccount:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        account_id: { type: string, nullable: true }
        entity_id: { type: string, nullable: true }
        compliance_category: { type: string, nullable: true, enum: [commingled_cash, customer_balance] }
        type: { type: string, example: bookkeeping_account }