Modern Treasury BulkResult API

openapi: 3.2.0
info:
  title: Modern Treasury AccountCapability Bulk Result API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: BulkResult
paths:
  /api/bulk_results:
    get:
      summary: list bulk_results
      tags:
      - BulkResult
      operationId: listBulkResults
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type:
          - string
          - 'null'
        required: false
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - successful
          - failed
        required: false
        description: One of successful or failed.
      - name: request_type
        in: query
        schema:
          type: string
          enum:
          - bulk_request
        required: false
        description: The type of the request that created this result. bulk_request is the only supported `request_type`
      - name: request_id
        in: query
        schema:
          type: string
        required: false
        description: Unique identifier for the request that created this bulk result. This is the ID of the bulk request when `request_type` is bulk_request
      - name: entity_type
        in: query
        schema:
          type: string
          enum:
          - payment_order
          - ledger_account
          - ledger_transaction
          - expected_payment
          - transaction
          - entity_link
          - transaction_line_item
          - bulk_error
        required: false
        description: The type of the request that created this result. bulk_request is the only supported `request_type`
      - name: entity_id
        in: query
        schema:
          type: string
        required: false
        description: Unique identifier for the result entity object.
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type:
                - string
                - 'null'
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type:
                - integer
                - 'null'
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/bulk_result'
        '401':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '403':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/bulk_results/{id}:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    get:
      summary: get bulk_result
      tags:
      - BulkResult
      operationId: getBulkResult
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulk_result'
        '401':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '403':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    expected_payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        external_id:
          type:
          - string
          - 'null'
          description: An optional user-defined 180 character unique identifier.
        amount_upper_bound:
          type:
          - integer
          - 'null'
          description: The highest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        amount_lower_bound:
          type:
          - integer
          - 'null'
          description: The lowest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        direction:
          type:
          - string
          - 'null'
          enum:
          - credit
          - debit
          description: One of credit or debit. When you are receiving money, use credit. When you are being charged, use debit.
        internal_account_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the Internal Account for the expected payment.
        type:
          $ref: '#/components/schemas/expected_payment_type'
        currency:
          $ref: '#/components/schemas/currency'
          description: Must conform to ISO 4217. Defaults to the currency of the internal account.
        date_upper_bound:
          type:
          - string
          - 'null'
          format: date
          description: 'The latest date the payment may come in. Format: yyyy-mm-dd'
        date_lower_bound:
          type:
          - string
          - 'null'
          format: date
          description: 'The earliest date the payment may come in. Format: yyyy-mm-dd'
        description:
          type:
          - string
          - 'null'
          description: An optional description for internal use.
        statement_descriptor:
          type:
          - string
          - 'null'
          description: The statement description you expect to see on the transaction. For ACH payments, this will be the full line item passed from the bank. For wire payments, this will be the OBI field on the wire. For check payments, this will be the memo field.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        counterparty_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the counterparty you expect for this payment.
        remittance_information:
          type:
          - string
          - 'null'
          description: For `ach`, this field will be passed through on an addenda record. For `wire` payments the field will be passed through as the "Originator to Beneficiary Information", also known as OBI or Fedwire tag 6000.
        reconciliation_groups:
          type:
          - object
          - 'null'
          description: The reconciliation groups you have for this payment.
        reconciliation_filters:
          type:
          - object
          - 'null'
          description: The reconciliation filters you have for this payment.
        reconciliation_rule_variables:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/reconciliation_rule_variable'
          description: An array of reconciliation rule variables for this payment.
        amount_reconciled:
          type:
          - integer
          - 'null'
          description: The amount reconciled for this expected payment. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        amount_reconciled_direction:
          type:
          - string
          - 'null'
          enum:
          - credit
          - debit
          description: One of credit or debit. Indicates whether amount_reconciled is a credit or debit amount.
        amount_unreconciled:
          type:
          - integer
          - 'null'
          description: The amount that remains unreconciled for this expected payment. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        amount_unreconciled_direction:
          type:
          - string
          - 'null'
          enum:
          - credit
          - debit
          description: One of credit or debit. Indicates whether amount_unreconciled is a credit or debit amount.
        transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the Transaction this expected payment object has been matched to.
        transaction_line_item_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the Transaction Line Item this expected payment has been matched to.
        status:
          type: string
          enum:
          - archived
          - partially_reconciled
          - reconciled
          - unreconciled
          description: One of unreconciled, partially_reconciled, reconciled, or archived.
        reconciliation_method:
          type:
          - string
          - 'null'
          enum:
          - automatic
          - manual
          description: One of manual if this expected payment was manually reconciled in the dashboard, automatic if it was automatically reconciled by Modern Treasury, or null if it is unreconciled.
        ledger_transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the ledger transaction linked to the expected payment.
      additionalProperties: false
      minProperties: 31
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - external_id
      - amount_upper_bound
      - amount_lower_bound
      - direction
      - internal_account_id
      - type
      - currency
      - date_upper_bound
      - date_lower_bound
      - description
      - statement_descriptor
      - metadata
      - counterparty_id
      - remittance_information
      - reconciliation_groups
      - reconciliation_filters
      - reconciliation_rule_variables
      - amount_reconciled
      - amount_reconciled_direction
      - amount_unreconciled
      - amount_unreconciled_direction
      - transaction_id
      - transaction_line_item_id
      - status
      - reconciliation_method
      - ledger_transaction_id
    reconciliation_rule_variable:
      type: object
      properties:
        amount_upper_bound:
          type: integer
          description: The highest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        amount_lower_bound:
          type: integer
          description: The lowest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of credit or debit. When you are receiving money, use credit. When you are being charged, use debit.
        internal_account_id:
          type: string
          format: uuid
          description: The ID of the Internal Account for the expected payment
        type:
          type:
          - string
          - 'null'
          enum:
          - ach
          - au_becs
          - bacs
          - book
          - card
          - chats
          - check
          - cross_border
          - dk_nets
          - eft
          - gb_fps
          - hu_ics
          - interac
          - masav
          - mx_ccen
          - neft
          - nics
          - nz_becs
          - pl_elixir
          - provxchange
          - ro_sent
          - rtp
          - se_bankgirot
          - sen
          - sepa
          - sg_giro
          - sic
          - signet
          - sknbi
          - stablecoin
          - wire
          - zengin
          description: One of ach, au_becs, bacs, book, check, eft, interac, provxchange, rtp, sen, sepa, signet wire
        currency:
          $ref: '#/components/schemas/currency'
          description: Must conform to ISO 4217. Defaults to the currency of the internal account
        date_upper_bound:
          type:
          - string
          - 'null'
          format: date
          description: The latest date the payment may come in. Format is yyyy-mm-dd
        date_lower_bound:
          type:
          - string
          - 'null'
          format: date
          description: The earliest date the payment may come in. Format is yyyy-mm-dd
        counterparty_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the counterparty you expect for this payment
        custom_identifiers:
          type:
          - object
          - 'null'
          description: A hash of custom identifiers for this payment
          additionalProperties:
            type: string
      additionalProperties: false
      minProperties: 10
      required:
      - amount_upper_bound
      - amount_lower_bound
      - direction
      - internal_account_id
    ledger_entry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type:
          - string
          - 'null'
          format: date-time
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000. Can be any integer up to 36 digits.
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `credit`, `debit`. Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that wire, rtp, and check payments will always be `credit`.
          _x-stainless-modelDefPath: $shared.transaction_direction
        status:
          type: string
          enum:
          - archived
          - pending
          - posted
          description: Equal to the state of the ledger transaction when the ledger entry was created. One of `pending`, `posted`, or `archived`.
        ledger_account_id:
          type: string
          format: uuid
          description: The ledger account that this ledger entry is associated with.
        ledger_account_lock_version:
          type:
          - integer
          - 'null'
          description: Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See our post about Designing the Ledgers API with Optimistic Locking for more details.
        ledger_account_currency:
          type: string
          description: The currency of the ledger account.
        ledger_account_currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
        ledger_transaction_id:
          type: string
          description: The ledger transaction that this ledger entry is associated with.
        resulting_ledger_account_balances:
          $ref: '#/components/schemas/ledger_balances'
          description: The pending, posted, and available balances for this ledger entry's ledger account. The posted balance is the sum of all posted entries on the account. The pending balance is the sum of all pending and posted entries on the account. The available balance is the posted incoming entries minus the sum of the pending and posted outgoing amounts. Please see https://docs.moderntreasury.com/docs/transaction-status-and-balances for more details.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
      additionalProperties: false
      minProperties: 17
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - amount
      - effective_at
      - direction
      - status
      - ledger_account_id
      - ledger_account_lock_version
      - ledger_account_currency
      - ledger_account_currency_exponent
      - ledger_transaction_id
      - resulting_ledger_account_balances
      - metadata
    accounting:
      type: object
      deprecated: true
      properties:
        account_id:
          type:
          - string
          - 'null'
          format: uuid
          deprecated: true
          description: The ID of one of your accounting categories. Note that these will only be accessible if your accounting system has been connected.
        class_id:
          type:
          - string
          - 'null'
          format: uuid
          deprecated: true
          description: The ID of one of the class objects in your accounting system. Class objects track segments of your business independent of client or project. Note that these will only be accessible if your accounting system has been connected.
    ledger_balances:
      type: object
      properties:
        pending_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The pending_balance is the sum of all pending and posted entries.
        posted_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The posted_balance is the sum of all posted entries.
        available_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The available_balance is the sum of all posted inbound entries and pending outbound entries. For credit normal, available_amount = posted_credits - pending_debits; for debit normal, available_amount = posted_debits - pending_credits.
      additionalProperties: false
      minProperties: 3
      required:
      - pending_balance
      - posted_balance
      - available_balance
    payment_order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        type:
          $ref: '#/components/schemas/payment_order_type'
        subtype:
          $ref: '#/components/schemas/payment_order_subtype'
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000 (cents). For RTP, the maximum amount allowed by the network is $100,000.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `credit`, `debit`. Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that wire, rtp, and check payments will always be `credit`.
        priority:
          type: string
          enum:
          - high
          - normal
          description: Either `normal` or `high`. For ACH and EFT payments, `high` represents a same-day ACH or EFT transfer, respectively. For check payments, `high` can mean an overnight check rather than standard mail.
        originating_account_id:
          type: string
          format: uuid
          description: The ID of one of your organization's internal accounts.
        receiving_account_id:
          type: string
          format: uuid
          description: The receiving account ID. Can be an `external_account` or `internal_account`.
        currency:
          $ref: '#/components/schemas/currency'
          description: Defaults to the currency of the originating account.
        accounting:
          $ref: '#/components/schemas/accounting'
        accounting_category_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of one of your accounting categories. Note that these will only be accessible if your accounting system has been connected.
          deprecated: true
        accounting_ledger_class_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of one of your accounting ledger classes. Note that these will only be accessible if your accounting system has been connected.
          deprecated: true
        effective_date:
          type: string
          format: date
          description: 'Date transactions are to be posted to the participants'' account. Defaults to the current business day or the next business day if the current day is a bank holiday or weekend. Format: yyyy-mm-dd.'
        description:
          type:
          - string
          - 'null'
          description: An optional description for internal use.
        statement_descriptor:
          type:
          - string
          - 'null'
          description: An optional descriptor which will appear in the receiver's statement. For `check` payments this field will be used as the memo line. For `ach` the maximum length is 10 characters. Note that for ACH payments, the name on your bank account will be included automatically by the bank, so you can use the characters for other useful information. For `eft` the maximum length is 15 characters.
        remittance_information:
          type:
          - string
          - 'null'
          description: For `ach`, this field will be passed through on an addenda record. For `wire` payments the field will be passed through as the "Originator to Beneficiary Information", also known as OBI or Fedwire tag 6000.
        process_after:
          type:
          - string
          - 'null'
          format: date-time
          description: If present, Modern Treasury will not process the payment until after this time. If `process_after` is past the cutoff for `effective_date`, `process_after` will take precedence and `effective_date` will automatically update to reflect the earliest possible sending date after `process_after`. Format is ISO8601 timestamp.
        purpose:
          type:
          - string
          - 'null'
          description: For `wire`, this is usually the purpose which is transmitted via the "InstrForDbtrAgt" field in the ISO20022 file. For `eft`, this field is the 3 digit CPA Code that will be attached to the payment.
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
        charge_bearer:
          type:
          - string
          - 'null'
          enum:
          - shared
          - sender
          - receiver
          description: The party that will pay the fees for the payment order. See https://docs.moderntreasury.com/payments/docs/charge-bearer to understand the differences between the options.
        foreign_exchange_indicator:
          type:
          - string
          - 'null'
          enum:
          - fixed_to_variable
          - variable_to_fixed
          description: Indicates the type of FX transfer to initiate, can be either `variable_to_fixed`, `fixed_to_variable`, or `null` if the payment order currency matches the originating account currency.
        foreign_exchange_contract:
          type:
          - string
          - 'null'
          description: If present, indicates a specific foreign exchange contract number that has been generated by your financial institution.
        nsf_protected:
          type: boolean
          description: A boolean to determine if NSF Protection is enabled for this payment order. Note that this setting must also be turned on in your organization settings page.
        originating_party_name:
          type:
          - string
          - 'null'
          description: If present, this will replace your default company name on receiver's bank statement. This field can only be used for ACH payments currently. For ACH, only the first 16 characters of this string will be used. Any additional characters will be truncated.
        ultimate_originating_party_name:
          type:
          - string
          - 'null'
          description: Name of the ultimate originator of the payment order.
        ultimate_originating_party_identifier:
          type:
          - string
          - 'null'
          description: Identifier of the ultimate originator of the payment order.
        ultimate_receiving_party_name:
          type:
          - string
          - 'null'
        ultimate_receiving_party_identifier:
          type:
          - string
          - 'null'
        send_remittance_advice:
          type:
          - boolean
          - 'null'
          description: Send an email to the counterparty when the payment order is sent to the bank. If `null`, `send_remittance_advice` on the Counterparty is used.
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: RFP payments require an expires_at. This value must be past the effective_date.
        reconciliation_status:
          type: string
          enum:
          - unreconciled
          - tentatively_reconciled
          - reconciled
          description: One of `unreconciled`, `tentatively_reconciled` or `reconciled`.
        external_id:
          type:
          - string
          - 'null'
          description: An optional user-defined 180 character unique identifier.
        status:
          type: string
          enum:
          - approved
          - cancelled
          - completed
          - denied
          - failed
          - held
          - needs_approval
          - pending
          - processing
          - returned
          - reversed
          - sent
          - stopped
          description: The current status of the payment order.
        receiving_account_type:
          type: string
          enum:
          - internal_account
          - external_account
        ultimate_originating_account:
          type:
          - object
          - 'null'
          description: The account to which the originating of this payment should be attributed to. Can be a `virtual_account` or `internal_account`.
          anyOf:
          - $ref: '#/components/schemas/virtual_account'
          - $ref: '#/components/schemas/internal_account'
        ultimate_originating_account_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ultimate originating account ID. Can be a `virtual_account` or `internal_account`.
        ultimate_originating_account_type:
          type:
          - string
          - 'null'
          enum:
          - internal_account
          - virtual_account
        counterparty_id:
          type:
          - string
          - 'null'
          format: uuid
          description: If the payment order is tied to a specific Counterparty, their id will appear, otherwise `null`.
        transaction_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The IDs of all the transactions associated to this payment order. Usually, you will only have a single transaction ID. However, if a payment order initially results in a Return, but gets redrafted and is later successfully completed, it can have many transactions.
        ledger_transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the ledger transaction linked to the payment order.
        current_return:
          $ref: '#/components/schemas/return'
          description: If the payment order's status is `returned`, this will include the return object's data.
        current_hold:
          $ref: '#/components/schemas/hold'
          description: If the payment order's status is `held`, this will include the hold object's data.
        reference_numbers:
          type: array
          items:
            $ref: '#/components/schemas/payment_reference'
        vendor_failure_reason:
          type:
          - string
          - 'null'
          description: This field will be populated if a vendor failure occurs. Logic shouldn't be built on its value as it is free-form.
        foreign_exchange_rate:
          $ref: '#/components/schemas/foreign_exchange_rate'
          description: Associated serialized foreign exchange rate information.
        vendor_attributes:
          type:
          - object
          - 'null'
          description: Additional vendor specific fields for this payment. Data must be represented as key-value pairs.
        batch_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the batch in which the payment order is included. Only populated after the payment order begins processing.
      additionalProperties: false
      minProperties: 52
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - type
      - subtype
      - amount
      - direction
      - priority
      - originating_account_id
      - receiving_account_id
      - currency
      - accounting
      - accounting_category_id
      - accounting_ledger_class_id
      - effective_date
      - description
      - statement_descriptor
      - remittance_information
      - process_after
      - purpose
      - metadata
      - charge_bearer
      - foreign_exchange_indicator
      - foreign_exchange_contract
      - nsf_protected
      - originating_party_name
      - ultimate_originating_party_name
      - ultimate_originating_party_identifier
      - ultimate_receiving_party_name
      - ultimate_receiving_party_identifier
      - send_remittance_advice
      - expires_at
      - reconciliation_status
      - external_id
      - status
      - receiving_account_type
      - ultimate_originating_account
      - ultimate_originating_account_id
      - ultimate_originating_account_type
      - counterparty_id
      - transaction_ids
      - ledger_transaction_id
      - current_return
      - current_hold
      - reference_numbers
      - vendor_failure_reason
      - foreign_exchange_rate
      - vendor_attributes
      - batch_id
    address:
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if th

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-bulkresult-api-openapi.yml