Bulk Requests

A Bulk Request represents a request to asynchronously operate on a given resource in bulk. When creating a Bulk Request, Modern Treasury requires an action_type, a resource_type and an array of resources. Each item in resources represents the input parameters for a single request to perform an action_type operation on resource_type resource.

For example, to create Payment Orders in bulk, the action_type is create, the resource_type is payment_order and each item in the resources array has valid create-payment-order-params.

When processing a Bulk Request, Modern Treasury generates one Bulk Result for each row in the resources array. As each array item is processed, Modern Treasury moves the associated Bulk Result to either the successful or failed state, and increments summary result counts (success_result_count, failed_result_count) on the Bulk Request object accordingly. When all resources have been processed, Modern Treasury transitions the Bulk Request to the completed state.

Row-level processing results may be monitored or reviewed using the List Bulk Results API, by specifying the request_type=bulk_request and requester_id=BULK_REQUEST_ID.

Please be advised that certain parameters are not supported when using bulk requests for ledger transactions. Specifically, the following parameters cannot be included in bulk ledger transaction requests:
ledger_entries.lock_version
ledger_entries.show_resulting_ledger_account_balances
ledger_account_category_balance_locks
These limitations are in place to ensure optimal performance when processing large volumes. For workflows requiring these parameters, we recommend using single API requests instead of bulk operations. For more information about synchronous and asynchronous processing of ledger entries see our documentation on designing a ledger for concurrency

AttributeDescription
id
string
Unique identifier for the bulk request
action_type
string
The action to be performed with each item in the resources array.
One of create, update or delete.
resource_type
string
The type of resource to being operated on. One of payment_order, expected_payment, transaction, or ledger_transaction
status
string
One of pending, processing or completed
total_resource_count
int32
Total number of items in the resources array. Once a bulk request is completed, success_result_count + failed_result_count will be equal to total_result_count.
success_result_count
int32
Total number of successful bulk results so far for this request
failed_result_count
int32
Total number of failed bulk results so far for this request
metadata
object
Additional data represented as key-value pairs. Both the key and value must be strings. See Metadata.
live_mode
boolean
This field will be true if this bulk request was created with a live API key or false if created with a sandbox API key.
{
  "id": "91c9117f-4855-419c-ad57-0801a58553d4",
  "object": "bulk_request",
  "live_mode": true,
  "action_type": "create",
  "resource_type": "payment_order",
  "status": "pending",
  "total_resource_count": 10,
  "success_result_count": 0,
  "failed_result_count": 0,
  "created_at": "2023-08-25T14:02:52Z",
  "updated_at": "2023-08-25T14:02:52Z"
}