v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Transactions API

Create a Transaction Annotation

Use this endpoint to create a transaction with no financial impact, to include operations in the ledger, but without impacting account balances.

Note: the pending field is accepted in the request body but ignored for annotations — an annotation's status is always set to NOTED.

post/v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/annotation

Path parameters

organization_idstring uuid required

The unique identifier of the Organization associated with the Ledger.

ledger_idstring uuid required

The unique identifier of the associated Ledger.

Headers

Content-Typestring

The type of media of the resource. Recommended value is application/json.

X-Request-Idstring uuid

A unique identifier used to trace and track each request.

Authorizationstring

Bearer JWT token for authentication. Required when PLUGIN_AUTH_ENABLED=true (enforced in multi-tenant deployments). Optional in default OSS single-tenant mode. Format: Bearer <token>

X-Idempotencystring

A unique key that ensures transaction idempotency. If not provided, the system automatically generates a SHA-256 hash based on the request body. Keys are scoped per organization and ledger.

Always validate the X-Idempotency-Replayed response header to distinguish new transactions from cached replays.

See Retries and idempotency for best practices.

X-TTLinteger

The time-to-live for the idempotency key, defined in seconds. Defaults to 300 seconds (5 minutes) if not provided. Only the TTL from the first request is used; changing it on retries has no effect.

See Retries and idempotency for details.

Request body

chartOfAccountsGroupNamestring

The chart of accounts group name which categorizes this transaction under a specific group.

descriptionstring

A description for the transaction.

codestring

Transaction code for reference.

pendingboolean

Whether the transaction should be created in pending state.

routestring

Deprecated. Use routeId instead. Legacy route identifier kept for backward compatibility; accepted from the client but not used for routing validation.

routeIdstring uuid

The unique identifier (UUID) of the Transaction Route associated with this transaction. Important: When Transaction Routing validation is enabled for your Ledger, this field becomes mandatory and must match an existing id from your configured Transaction Routes. However, when validation is disabled (default behavior), this field is optional.

transactionDatestring

The time when the transaction was made. Used to add past transactions. Must be a date in the past.

metadataMetadata

An object containing key-value pairs to add as metadata, where the field name is the key and the field value is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'.

Constraints: keys must be at most 100 characters; string values at most 2000 characters. Nested objects are not allowed (values must be string, number, or boolean), the structure may not exceed a maximum depth of 10, and a maximum of 100 keys is permitted.

Example request

{
  "chartOfAccountsGroupName": "FUNDING",
  "code": "TR12345"
}

Response

Indicates that the request was successful and the response contains the expected data.

The response includes the X-Idempotency-Replayed header.

If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request.

See Retries and idempotency for more details.

idstring uuid

The unique identifier of the transaction.

parentTransactionIdstring uuid nullable

The unique identifier of the parent/original transaction for reversals. This field is populated by the server when a transaction is reverted and should be treated as read-only by clients.

organizationIdstring uuid

The unique identifier of the Organization.

ledgerIdstring uuid

The unique identifier of the Ledger.

descriptionstring

Description of the transaction.

routestring

Specifies the Transaction Route associated with the transaction.

routeIdstring uuid

The unique identifier of the Transaction Route applied to this transaction.

amountstring

The sent amount.

assetCodestring

The name of the asset used in the operation.

chartOfAccountsGroupNamestring

The name of the chart-of-accounts group.

sourcestring[]

The list of accounts used as source.

destinationstring[]

The list of accounts used as destination.

createdAtstring date-time

Timestamp of creation (UTC).

updatedAtstring date-time

Timestamp of last update (UTC).

deletedAtstring date-time nullable

Timestamp of soft deletion, if applicable (UTC).

metadataMetadata

An object containing key-value pairs to add as metadata, where the field name is the key and the field value is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'.