Skip to main content
The _bulk endpoint allows for efficient processing of multiple requests in a single operation. It supports streaming, parallel or sequential processing, and atomic execution.

​
Streaming support

Bulk requests can be streamed without requiring the entire request to be loaded into memory. To enable streaming, include one of the following content type headers in your HTTP request:
  • For a script stream, include content type application/vnd.formance.ledger.api.v2.bulk+script-stream
  • For a JSON stream, include content type application/vnd.formance.ledger.api.v2.bulk+json-stream

​
JSON stream format

For a JSON stream, elements should be sent one per line in the request body. Example: 
{"action": "CREATE_TRANSACTION", "data": {"postings": [{"source": "world", "amount": 100, "asset": "USD", "destination": "bank"}]}}
{"action": "CREATE_TRANSACTION", "data": {"postings": [{"source": "world", "amount": 200, "asset": "USD", "destination": "bank"}]}}

​
Parallel v. Sequential Processing

Bulk elements can be processed either in parallel or sequentially, controlled by the parallel query parameter:
  • parallel=true (default): Elements are processed in parallel, improving throughput.
  • parallel=false: Elements are processed sequentially, maintaining order.

​
Atomic Bulk Execution

Bulk elements can be committed atomically or independently using the atomic query parameter:
  • atomic=true: The entire batch is committed as a single transaction. If any element fails, the entire batch is rolled back.
  • atomic=false: Each element is processed independently. If one element fails, it does not affect the others.
Since requests can be processed either in parallel or atomically, you cannot set parallel=true and atomic=true at the same time.

​
Usage Examples

​
Script streaming

To send a bulk request with script streaming, parallel processing enabled and atomic execution disabled: 
curl -H "Authorization: Bearer $(fctl cloud generate-personal-token)" \
     -X POST <stack-url>/api/ledger/v2/<ledger-name>/_bulk?parallel=true&atomic=false \
     -H 'Content-Type: application/vnd.formance.ledger.api.v2.bulk+script-stream' \
     --data-binary @<stream file location>

​
JSON streaming

To send a bulk request with JSON streaming: 
curl -H "Authorization: Bearer $(fctl cloud generate-personal-token)" \
     -X POST <stack-url>/api/ledger/v2/<ledger-name>/_bulk?parallel=true&atomic=false \
     -H 'Content-Type: application/vnd.formance.ledger.api.v2.bulk+json-stream' \
     --data-binary @<json stream file location>
For more details on the bulk API parameters and response format, see the API Reference.
⌘I