Modern Treasury BulkRequest API
The BulkRequest API from Modern Treasury — 2 operation(s) for bulkrequest.
OpenAPI Specification
openapi: 3.0.1
info:
title: Modern Treasury AccountCapability BulkRequest 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: BulkRequest
paths:
/api/bulk_requests:
get:
summary: list bulk_requests
tags:
- BulkRequest
operationId: listBulkRequests
security:
- basic_auth: []
parameters:
- name: after_cursor
in: query
schema:
type: string
nullable: true
required: false
- name: per_page
in: query
required: false
schema:
type: integer
- name: status
in: query
schema:
type: string
enum:
- pending
- processing
- completed
required: false
description: One of pending, processing, or completed.
- name: resource_type
in: query
schema:
type: string
enum:
- payment_order
- ledger_account
- ledger_transaction
- expected_payment
- transaction
- transaction_line_item
- entity_link
required: false
description: One of payment_order, expected_payment, or ledger_transaction.
- name: action_type
in: query
schema:
type: string
enum:
- create
- update
- delete
required: false
description: One of create, or update.
- $ref: '#/components/parameters/metadata_query'
responses:
'200':
description: successful
headers:
X-After-Cursor:
schema:
type: string
nullable: true
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
nullable: true
description: The current `per_page`.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/bulk_request'
'401':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
'403':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
post:
summary: create bulk_request
tags:
- BulkRequest
operationId: createBulkRequest
security:
- basic_auth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: This key should be something unique, preferably something like an UUID.
schema:
type: string
responses:
'201':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/bulk_request'
'401':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
'403':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
'422':
description: unsuccessful
content:
application/json:
schema:
$ref: '#/components/schemas/error_message'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulk_request_create_request'
/api/bulk_requests/{id}:
parameters:
- name: id
in: path
description: id
required: true
schema:
type: string
get:
summary: get bulk_request
tags:
- BulkRequest
operationId: getBulkRequest
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/bulk_request'
'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:
payment_order_subtype:
type: string
enum:
- 0C
- 0N
- 0S
- CCD
- CIE
- CTX
- IAT
- PPD
- TEL
- WEB
- au_becs
- bacs
- base
- chats
- dk_nets
- eft
- ethereum
- hu_ics
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- polygon
- ro_sent
- se_bankgirot
- sepa
- sg_giro
- sic
- sknbi
- solana
- zengin
nullable: true
description: An additional layer of classification for the type of payment order you are doing. This field is only used for `ach` payment orders currently. For `ach` payment orders, the `subtype` represents the SEC code. We currently support `CCD`, `PPD`, `IAT`, `CTX`, `WEB`, `CIE`, and `TEL`.
x-stainless-renameMap:
bacs_new_instruction: 0C
bacs_cancellation_instruction: 0N
bacs_conversion_instruction: 0S
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
nullable: true
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
format: date
nullable: true
description: The latest date the payment may come in. Format is yyyy-mm-dd
date_lower_bound:
type: string
format: date
nullable: true
description: The earliest date the payment may come in. Format is yyyy-mm-dd
counterparty_id:
type: string
format: uuid
nullable: true
description: The ID of the counterparty you expect for this payment
custom_identifiers:
type: object
description: A hash of custom identifiers for this payment
nullable: true
additionalProperties:
type: string
additionalProperties: false
minProperties: 10
required:
- amount_upper_bound
- amount_lower_bound
- direction
- internal_account_id
external_account_type:
type: string
enum:
- base_wallet
- cash
- checking
- crypto_wallet
- ethereum_wallet
- general_ledger
- loan
- non_resident
- other
- overdraft
- polygon_wallet
- savings
- solana_wallet
description: Can be `checking`, `savings` or `other`.
transaction_create_request:
type: object
properties:
amount:
type: integer
description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
direction:
type: string
description: Either `credit` or `debit`.
vendor_description:
type: string
nullable: true
description: The transaction detail text that often appears in on your bank statement and in your banking portal.
vendor_code:
type: string
description: When applicable, the bank-given code that determines the transaction's category. For most banks this is the BAI2/BTRS transaction code.
nullable: true
vendor_code_type:
type: string
description: The type of `vendor_code` being reported. Can be one of `bai2`, `bankprov`, `bnk_dev`, `cleartouch`, `currencycloud`, `cross_river`, `dc_bank`, `dwolla`, `evolve`, `goldman_sachs`, `iso20022`, `jpmc`, `mx`, `signet`, `silvergate`, `swift`, `us_bank`, or others.
nullable: true
vendor_customer_id:
type: string
description: An identifier given to this transaction by the bank, often `null`.
nullable: true
as_of_date:
type: string
nullable: true
format: date
description: The date on which the transaction occurred.
internal_account_id:
type: string
format: uuid
description: The ID of the relevant Internal Account.
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
posted:
type: boolean
description: This field will be `true` if the transaction has posted to the account.
type:
type: string
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
- other
description: The type of the transaction. Examples could be `card, `ach`, `wire`, `check`, `rtp`, `book`, or `sen`.
nullable: true
required:
- amount
- direction
- vendor_code
- vendor_code_type
- as_of_date
- internal_account_id
ledger_transaction_update_request:
type: object
properties:
description:
type: string
description: An optional description for internal use.
nullable: true
status:
type: string
enum:
- archived
- pending
- posted
description: To post a ledger transaction at creation, use `posted`.
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
effective_at:
type: string
format: date-time
description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
ledger_entries:
type: array
items:
$ref: '#/components/schemas/ledger_entry_create_request'
description: An array of ledger entry objects.
ledgerable_type:
type: string
enum:
- expected_payment
- incoming_payment_detail
- payment_order
- return
- reversal
description: If the ledger transaction can be reconciled to another object in Modern Treasury, the type will be populated here, otherwise null. This can be one of payment_order, incoming_payment_detail, expected_payment, return, or reversal.
ledgerable_id:
type: string
format: uuid
description: If the ledger transaction can be reconciled to another object in Modern Treasury, the id will be populated here, otherwise null.
external_id:
type: string
description: A unique string to represent the ledger transaction. Only one pending or posted ledger transaction may have this ID in the ledger.
nullable: true
ledger_account_create_request:
type: object
properties:
name:
type: string
description: The name of the ledger account.
description:
type: string
description: The description of the ledger account.
nullable: true
normal_balance:
type: string
enum:
- credit
- debit
description: The normal balance of the ledger account.
_x-stainless-modelDefPath: $shared.transaction_direction
ledger_id:
type: string
format: uuid
description: The id of the ledger that this account belongs to.
currency:
type: string
description: The currency of the ledger account.
currency_exponent:
type: integer
description: The currency exponent of the ledger account.
nullable: true
ledger_account_category_ids:
type: array
items:
type: string
format: uuid
description: The array of ledger account category ids that this ledger account should be a child of.
ledgerable_id:
type: string
format: uuid
description: If the ledger account links to another object in Modern Treasury, the id will be populated here, otherwise null.
ledgerable_type:
type: string
enum:
- counterparty
- external_account
- internal_account
- virtual_account
description: If the ledger account links to another object in Modern Treasury, the type will be populated here, otherwise null. The value is one of internal_account or external_account.
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
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
required:
- name
- normal_balance
- ledger_id
- currency
currency:
type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BCH
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTC
- BTN
- BWP
- BYN
- BYR
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNH
- CNY
- COP
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EEK
- EGP
- ERN
- ETB
- ETH
- EUR
- EURC
- FJD
- FKP
- GBP
- GBX
- GEL
- GGP
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- IMP
- INR
- IQD
- IRR
- ISK
- JEP
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MRU
- MTL
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- OP
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- PYUSD
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SKK
- SLE
- SLL
- SOS
- SRD
- SSP
- STD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMM
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- USDB
- USDC
- USDG
- USDP
- USDT
- UYU
- UZS
- VEF
- VES
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XCG
- XDR
- XFU
- XOF
- XPD
- XPF
- XPT
- XTS
- YER
- ZAR
- ZMK
- ZMW
- ZWD
- ZWG
- ZWL
- ZWN
- ZWR
description: Three-letter ISO currency code.
error_message:
type: object
properties:
errors:
type: object
properties:
code:
type: string
enum:
- parameter_invalid
- parameter_missing
- resource_not_found
- not_found
- forbidden
- invalid_ip
- invalid_key
- header_invalid
- expired_key
- conflict
- too_many_requests
message:
type: string
parameter:
type: string
required:
- errors
address_request:
type: object
properties:
line1:
type: string
nullable: true
line2:
type: string
nullable: true
locality:
type: string
nullable: true
description: Locality or City.
region:
type: string
nullable: true
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
nullable: true
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
nullable: true
expected_payment_create_request:
type: object
properties:
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
amount_upper_bound:
type: integer
nullable: true
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
nullable: true
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
nullable: true
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
nullable: true
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'
nullable: true
description: Must conform to ISO 4217. Defaults to the currency of the internal account.
date_upper_bound:
type: string
format: date
nullable: true
description: 'The latest date the payment may come in. Format: yyyy-mm-dd'
date_lower_bound:
type: string
format: date
nullable: true
description: 'The earliest date the payment may come in. Format: yyyy-mm-dd'
description:
type: string
nullable: true
description: An optional description for internal use.
statement_descriptor:
type: string
nullable: true
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
format: uuid
description: The ID of the counterparty you expect for this payment.
nullable: true
remittance_information:
type: string
nullable: true
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
nullable: true
description: The reconciliation groups you have for this payment.
reconciliation_filters:
type: object
nullable: true
description: The reconciliation filters you have for this payment.
reconciliation_rule_variables:
type: array
nullable: true
items:
$ref: '#/components/schemas/reconciliation_rule_variable'
description: An array of reconciliation rule variables for this payment.
amount_reconciled:
type: integer
nullable: true
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
nullable: true
enum:
- credit
- debit
description: One of credit or debit. Indicates whether amount_reconciled is a credit or debit amount.
amount_unreconciled:
type: integer
nullable: true
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
nullable: true
enum:
- credit
- debit
description: One of credit or debit. Indicates whether amount_unreconciled is a credit or debit amount.
line_items:
type: array
items:
$ref: '#/components/schemas/line_item_request'
ledger_transaction:
$ref: '#/components/schemas/ledger_transaction_create_request'
description: Specifies a ledger transaction object that will be created with the expected payment. If the ledger transaction cannot be created, then the expected payment creation will fail. The resulting ledger transaction will mirror the status of the expected payment.
ledger_transaction_id:
type: string
format: uuid
description: Either ledger_transaction or ledger_transaction_id can be provided. Only a pending ledger transaction can be attached upon expected payment creation. Once the expected payment is created, the status of the ledger transaction tracks the expected payment automatically.
payment_order_type:
type: string
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`, `se_bankgirot`, `eft`, `wire`, `check`, `sen`, `book`, `rtp`, `sepa`, `bacs`, `au_becs`, `interac`, `neft`, `nics`, `nz_national_clearing_code`, `sic`, `signet`, `provexchange`, `zengin`.
expected_payment_type:
type: string
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
nullable: true
description: 'One of: ach, au_becs, bacs, book, check, eft, interac, provxchange, rtp, sen, sepa, signet, wire.'
payment_order_update_request:
type: object
properties:
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: Either `receiving_account` or `receiving_account_id` must be present. When using `receiving_account_id`, you may pass the id of an external account or an 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
format: uuid
nullable: true
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
format: uuid
nullable: true
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
nullable: true
description: An optional description for internal use.
statement_descriptor:
type: string
nullable: true
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
nullable: true
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
format: date-time
nullable: true
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
nullable: true
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
enum:
- shared
- sender
- receiver
nullable: true
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
enum:
- fixed_to_variable
- variable_to_fixed
nullable: true
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
nullable: true
description: If present, indicates a specific foreign exchange contract number that has been generated by your financial institution.
nsf_protected:
type: boolean
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-bulkrequest-api-openapi.yml