--- title: "Bulk request" method: POST path: "/v2/{ledger}/_bulk" tags: ["ledger.v2"] --- # Bulk request `POST /v2/{ledger}/_bulk` ## Path parameters - `ledger` string, required ## Query parameters - `continueOnFailure` boolean - `atomic` boolean - `parallel` boolean - `schemaVersion` string ## Request body - V2BulkElement[] - union - object - `action` string, required — The bulk action this element performs - `ik` string — Idempotency key scoped to this element, making it safe to retry the bulk request - `data` V2PostTransaction - `timestamp` string, date-time — The transaction time to record, letting you backdate or postdate the transaction. Defaults to current machine time if omitted. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `postings` V2Posting[] — Fund movements to apply. Mutually exclusive with script and template - `amount` integer, required — Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit - `asset` string, required — The asset being moved, optionally carrying a scale suffix such as USD/2 - `destination` string, required — Address of the account credited by this posting - `source` string, required — Address of the account debited by this posting - `script` object — A Numscript program executed to produce the postings. Mutually exclusive with postings - `template` string - `plain` string - `vars` object - `runtime` 'experimental-interpreter' | 'machine' — The numscript runtime used to execute the script. Uses "machine" by default, unless the "--experimental-numscript-interpreter" feature flag is passed. - `reference` string — Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions - `metadata` V2Metadata, required — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - `accountMetadata` object — Metadata to set on the accounts involved in the transaction, keyed by account address - `force` boolean — When true, lets source accounts overdraft without bound, bypassing the balance check. Applies to the postings form only - object - `action` string, required — The bulk action this element performs - `ik` string — Idempotency key scoped to this element, making it safe to retry the bulk request - `data` object - `targetId` union, required - string - integer - `targetType` 'TRANSACTION' | 'ACCOUNT', required - `metadata` object, required - object - `action` string, required — The bulk action this element performs - `ik` string — Idempotency key scoped to this element, making it safe to retry the bulk request - `data` object - `id` integer, required - `force` boolean - `atEffectiveDate` boolean - `metadata` V2Metadata — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - object - `action` string, required — The bulk action this element performs - `ik` string — Idempotency key scoped to this element, making it safe to retry the bulk request - `data` object - `targetId` union, required - string - integer - `targetType` 'TRANSACTION' | 'ACCOUNT', required - `key` string, required ## Response `200` OK - V2BulkResponse - `data` V2BulkElementResult[] — Result of each element of the bulk request, in submission order - union - object - `responseType` string, required — The action this result corresponds to - `logID` integer, required — Identifier of the log entry produced by this element - `data` V2Transaction, required — A transaction recorded in the ledger, carrying its postings, metadata and both bi-temporal timestamps - `insertedAt` string, date-time — The request time: when the transaction was actually written to the ledger. Set by the ledger, not the caller. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `updatedAt` string, date-time — When the transaction row was last modified, for example by a metadata change or a revert - `timestamp` string, date-time, required — The transaction time: when the transaction is considered to have occurred, also called the effective or booking date. This is the axis the ledger uses to compute balances and resolve point-in-time queries. Settable at creation, defaulting to current machine time if omitted, and immutable once written. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `postings` V2Posting[], required — The fund movements making up the transaction - `amount` integer, required — Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit - `asset` string, required — The asset being moved, optionally carrying a scale suffix such as USD/2 - `destination` string, required — Address of the account credited by this posting - `source` string, required — Address of the account debited by this posting - `reference` string — Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions - `metadata` V2Metadata, required — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - `id` integer, required — Unique sequential identifier for this transaction within the ledger - `reverted` boolean, required — Indicates if the transaction has been reverted - `revertedAt` string, date-time — When the transaction was reverted, on the request-time axis. Absent if the transaction has not been reverted - `preCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `preCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `template` string — Name of the transaction template this transaction was created from, if any - V2BaseBulkElementResult - `responseType` string, required — The action this result corresponds to - `logID` integer, required — Identifier of the log entry produced by this element - object - `responseType` string, required — The action this result corresponds to - `logID` integer, required — Identifier of the log entry produced by this element - `data` V2Transaction, required — A transaction recorded in the ledger, carrying its postings, metadata and both bi-temporal timestamps - `insertedAt` string, date-time — The request time: when the transaction was actually written to the ledger. Set by the ledger, not the caller. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `updatedAt` string, date-time — When the transaction row was last modified, for example by a metadata change or a revert - `timestamp` string, date-time, required — The transaction time: when the transaction is considered to have occurred, also called the effective or booking date. This is the axis the ledger uses to compute balances and resolve point-in-time queries. Settable at creation, defaulting to current machine time if omitted, and immutable once written. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `postings` V2Posting[], required — The fund movements making up the transaction - `amount` integer, required — Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit - `asset` string, required — The asset being moved, optionally carrying a scale suffix such as USD/2 - `destination` string, required — Address of the account credited by this posting - `source` string, required — Address of the account debited by this posting - `reference` string — Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions - `metadata` V2Metadata, required — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - `id` integer, required — Unique sequential identifier for this transaction within the ledger - `reverted` boolean, required — Indicates if the transaction has been reverted - `revertedAt` string, date-time — When the transaction was reverted, on the request-time axis. Absent if the transaction has not been reverted - `preCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `preCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `template` string — Name of the transaction template this transaction was created from, if any - V2BaseBulkElementResult - `responseType` string, required — The action this result corresponds to - `logID` integer, required — Identifier of the log entry produced by this element - object - `responseType` string, required — The action this result corresponds to - `logID` integer, required — Identifier of the log entry produced by this element - `errorCode` string, required - `errorDescription` string, required - `errorDetails` string - `errorCode` 'INTERNAL' | 'INSUFFICIENT_FUND' | 'VALIDATION' | 'CONFLICT' | 'COMPILATION_FAILED' | 'METADATA_OVERRIDE' | 'NOT_FOUND' | 'REVERT_OCCURRING' | 'ALREADY_REVERT' | 'NO_POSTINGS' | 'LEDGER_NOT_FOUND' | 'IMPORT' | 'TIMEOUT' | 'BULK_SIZE_EXCEEDED' | 'INTERPRETER_PARSE' | 'INTERPRETER_RUNTIME' | 'LEDGER_ALREADY_EXISTS' | 'SCHEMA_ALREADY_EXISTS' | 'SCHEMA_NOT_SPECIFIED' | 'OUTDATED_SCHEMA' — Machine-readable error code identifying the failure - `errorMessage` string — Human-readable description of the error ## Other responses - `400` — OK - `default` — Error --- [API](https://skmtc.dev/formancehq/apis/ledger-api.md) · [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/formancehq/ledger-api/revisions/fe945da1b75d/schema)