> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create an Unblock Transaction > Use this endpoint to create a transaction whose resulting operations are typed `UNBLOCK`. Midaz is agnostic about the business reason for unblocking funds — use the `metadata` field to record it. This endpoint always creates an immediately-posted, non-pending transaction: the `pending` field of the request body is ignored (overridden to `false`) — unblock transactions are never pending. The endpoint accepts the same body as the JSON create endpoint. ## OpenAPI ````yaml en/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock openapi: 3.1.0 info: title: Midaz Ledger API description: >- Complete API reference for Midaz Ledger services including organization management, ledger operations, assets, segments, portfolios, accounts, account types, transactions, operations, balances, operation routes, transaction routes, and metadata indexes. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock: post: tags: - Transactions API summary: Create an Unblock Transaction description: >- Use this endpoint to create a transaction whose resulting operations are typed `UNBLOCK`. Midaz is agnostic about the business reason for unblocking funds — use the `metadata` field to record it. This endpoint always creates an immediately-posted, non-pending transaction: the `pending` field of the request body is ignored (overridden to `false`) — unblock transactions are never pending. The endpoint accepts the same body as the JSON create endpoint. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/XIdempotency' - $ref: '#/components/parameters/XTTL' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTransactionRequest' example: chartOfAccountsGroupName: FUNDING description: Release previously blocked funds code: UNB-2026-001 transactionDate: '2026-06-23T12:00:00Z' metadata: reason: investigation cleared channel: api send: asset: BRL value: '1000' source: from: - accountAlias: '@source-account' balanceKey: default amount: asset: BRL value: '1000' description: Debit from the source distribute: to: - accountAlias: '@destination-account' balanceKey: default remaining: remaining description: Credit at destination responses: '201': description: >- Indicates that the resource was successfully created and the operation was completed as expected. 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](/en/reference/retries-idempotency) for more details. headers: X-Idempotency-Replayed: $ref: '#/components/headers/XIdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/CreateTransactionResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0073: $ref: '#/components/examples/Error0073' headers: {} '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0105: $ref: '#/components/examples/Error0105' headers: {} '409': description: >- Conflict — the idempotency key is already in use by a request that is still being processed. The `X-Idempotency-Replayed` header is included in the response and set to `false`. See [Retries and idempotency](/en/reference/retries-idempotency) for more details. headers: X-Idempotency-Replayed: $ref: '#/components/headers/XIdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0084: $ref: '#/components/examples/Error0084' '422': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0018: $ref: '#/components/examples/Error0018' Error0019: $ref: '#/components/examples/Error0019' headers: {} '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: The unique identifier of the Organization associated with the Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: The unique identifier of the associated Ledger. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid ContentType: name: Content-Type in: header description: >- The type of media of the resource. Recommended value is `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: A unique identifier used to trace and track each request. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > 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 ` XIdempotency: name: X-Idempotency in: header description: >- 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](/en/reference/retries-idempotency) for best practices. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string XTTL: name: X-TTL in: header description: >- 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](/en/reference/retries-idempotency) for details. required: false example: 3600 schema: type: integer schemas: CreateTransactionRequest: type: object nullable: true properties: chartOfAccountsGroupName: type: string maxLength: 256 description: >- The name of the chart-of-accounts group associated with the transaction. description: type: string maxLength: 256 description: A description for the transaction. pending: type: boolean description: >- Indicates whether the transaction should follow a two-step process: authorization followed by execution. When set to **true**, the transaction is created in a pending state, reserving funds (`on_hold`) without immediately moving them. A subsequent commit is required to finalize the transfer. default: false code: type: string maxLength: 100 description: Transaction code for reference. route: type: string deprecated: true description: >- **Deprecated.** Use `routeId` instead. Legacy route identifier kept for backward compatibility; accepted from the client but not used for routing validation. routeId: type: string format: uuid description: >- 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](/en/reference/midaz/create-transaction-route). However, when validation is disabled (default behavior), this field is **optional**. transactionDate: type: string description: >- The time when the transaction was made. Used to add past transactions. **Must be a date in the past**. send: type: object description: >- An object containing information about the transaction that will be sent. required: - asset - value - source - distribute properties: asset: type: string description: The code that identifies the asset that will be sent. value: type: string description: >- The amount that will be sent. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. source: $ref: '#/components/schemas/SourceRequest' distribute: $ref: '#/components/schemas/DistributeRequest' metadata: $ref: '#/components/schemas/Metadata' CreateTransactionResponse: type: object properties: id: type: string description: The unique identifier of the transaction. format: uuid parentTransactionId: type: string description: >- 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. format: uuid nullable: true organizationId: type: string format: uuid description: The unique identifier of the Organization. ledgerId: type: string description: The unique identifier of the Ledger. format: uuid description: type: string description: Description of the transaction. route: type: string description: Specifies the Transaction Route associated with the transaction. routeId: type: string format: uuid description: >- The unique identifier of the Transaction Route applied to this transaction. status: type: object description: The transaction status (pending, completed, reversed). properties: code: type: string description: Transaction status code. description: type: string description: Transaction status description. amount: type: string description: The sent amount. assetCode: type: string description: The name of the asset used in the operation. chartOfAccountsGroupName: type: string description: The name of the chart-of-accounts group. source: type: array description: The list of accounts used as source. items: type: string destination: type: array description: The list of accounts used as destination. items: type: string createdAt: type: string format: date-time description: Timestamp of creation (UTC). updatedAt: type: string format: date-time description: Timestamp of last update (UTC). deletedAt: type: string format: date-time description: Timestamp of soft deletion, if applicable (UTC). nullable: true operations: type: array items: $ref: '#/components/schemas/OperationResponse' metadata: $ref: '#/components/schemas/Metadata' ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. entityType: type: string description: >- The type of entity the error relates to (e.g. organization, ledger, account, transaction). Optional. fields: type: object additionalProperties: true description: Additional information about the fields that caused the error. SourceRequest: type: object required: - from description: An object containing information about the source accounts. properties: remaining: type: string description: >- Specifies how to handle any remaining amount at the source level after all `from` entries are processed. from: type: array description: >- The list of accounts that will be used as source. Each entry in the array must include one of the following fields: `amount`, `share`, or `remaining`. If an entry includes more than one of these fields, an error will occur. minItems: 1 items: type: object properties: accountAlias: type: string description: The alias for the account used in the operation. balanceKey: type: string description: >- The unique identifier of the balance. If you don't provide a value, Midaz uses the `default` balance automatically. To route funds to a specific balance, provide a previously [created balance key](/en/reference/midaz/create-a-balance). route: type: string deprecated: true description: >- **Deprecated.** Use `routeId` instead. Legacy route identifier kept for backward compatibility; accepted from the client but not used for routing validation. routeId: type: string format: uuid description: >- 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](/en/reference/midaz/create-transaction-route). However, when validation is disabled (default behavior), this field is **optional**. amount: $ref: '#/components/schemas/SendAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- The remaining amount or percentage. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. rate: type: object description: >- The exchange rate to apply when the transaction involves different assets. properties: from: type: string description: The source asset code for the exchange rate. to: type: string description: The target asset code for the exchange rate. value: type: string description: >- The exchange rate value. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. externalId: type: string format: uuid description: The external identifier for the exchange rate. description: type: string description: A description for the operation. chartOfAccounts: type: string deprecated: true description: >- The name of the Chart-of-Accounts that the operation belongs to. metadata: $ref: '#/components/schemas/Metadata' DistributeRequest: type: object required: - to description: >- An object containing the information of the account to which the amount will be transferred. properties: remaining: type: string description: >- Specifies how to handle any remaining amount at the distribute level after all `to` entries are processed. to: type: array description: >- A list of the accounts to which the amount will be transferred. Each entry in the array must include one of the following fields: `amount`, `share`, or `remaining` If an entry includes more than one of these fields, an error will occur. minItems: 1 items: type: object properties: accountAlias: type: string description: >- The unique identifier or the alias of the account that will receive the amount. balanceKey: type: string description: >- The unique identifier key for the account balance. If omitted, the `default` balance is used. Use a previously [created key](https://docs.lerian.studio/en/reference/midaz/create-a-balance) to route funds to a specific balance. route: type: string deprecated: true description: >- **Deprecated.** Use `routeId` instead. Legacy route identifier kept for backward compatibility; accepted from the client but not used for routing validation. routeId: type: string format: uuid description: >- 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](/en/reference/midaz/create-transaction-route). However, when validation is disabled (default behavior), this field is **optional**. amount: $ref: '#/components/schemas/DistributeAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- The remaining amount or percentage. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. rate: type: object description: >- The exchange rate to apply when the transaction involves different assets. properties: from: type: string description: The source asset code for the exchange rate. to: type: string description: The target asset code for the exchange rate. value: type: string description: >- The exchange rate value. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. externalId: type: string format: uuid description: The external identifier for the exchange rate. description: type: string description: A description for the operation. chartOfAccounts: type: string deprecated: true description: >- The name of the Chart-of-Accounts that the operation belongs to. metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- 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. OperationResponse: type: object properties: id: type: string description: The unique identifier of the Operation. format: uuid transactionId: type: string format: uuid description: The unique identifier of the Transaction. organizationId: type: string format: uuid description: The unique identifier of the Organization. ledgerId: type: string description: The unique identifier of the Ledger. format: uuid accountId: type: string description: The unique identifier of the Account. format: uuid accountAlias: type: string description: The alias for the account used in the operation. balanceId: type: string description: The unique identifier of the Balance. balanceKey: type: string description: The key identifier of the Balance. description: type: string description: A description for the operation. type: type: string description: >- The type of the operation. `OVERDRAFT` identifies system-generated companion operations on the internal `"overdraft"` balance — `direction` then carries the lifecycle semantics (`debit` for a draw, `credit` for a repayment). `BLOCK` and `UNBLOCK` identify operations produced by the block/unblock transaction endpoints; `direction` still carries the debit/credit semantics. enum: - CREDIT - DEBIT - ON_HOLD - RELEASE - OVERDRAFT - BLOCK - UNBLOCK assetCode: type: string description: The code that identifies the sent asset. chartOfAccounts: type: string description: The name of the Chart-of-Accounts that the operation belongs to. route: type: string deprecated: true description: >- **Deprecated.** Use `routeId` instead. Will be removed in the next major version. The unique ID of the operation route for this transaction leg. routeId: type: string format: uuid description: >- The unique identifier of the operation route associated with this operation. Companion overdraft operations inherit this value from the primary operation that triggered them. routeCode: type: string maxLength: 100 description: >- A human-readable code for the operation route, useful for audit trail and traceability. routeDescription: type: string description: >- The description of the operation route associated with this operation. direction: type: string enum: - debit - credit description: The direction of the operation in double-entry accounting. amount: type: object description: >- An object containing information about the amount used in the operation. properties: value: type: string description: The amount that will be sent. balance: type: object description: >- An object containing information about the balance before the operation. properties: available: type: string description: Previous available balance. onHold: type: string description: Amount on hold/reserved. version: type: integer description: Balance version, which is updated with each transaction. overdraftUsed: type: string description: >- The overdraft consumed by this balance before the operation, as a decimal string. `"0"` for operations that do not touch overdraft. balanceAfter: type: object description: >- An object containing information about the balance after the operation. properties: available: type: string description: Current available balance. onHold: type: string description: Amount on hold/reserved. version: type: integer description: Balance version, which is updated with each transaction. overdraftUsed: type: string description: >- The overdraft consumed by this balance after the operation, as a decimal string. `"0"` for operations that do not touch overdraft. status: type: object description: The transaction status (pending, completed, reversed). properties: code: type: string description: Transaction status code. description: type: string description: Transaction status description. nullable: true balanceAffected: type: boolean description: >- Indicates whether the operation had an impact on the account balance. createdAt: type: string format: date-time description: Timestamp of creation (UTC). updatedAt: type: string format: date-time description: Timestamp of last update (UTC). deletedAt: type: string format: date-time description: Timestamp of soft deletion, if applicable (UTC). nullable: true metadata: $ref: '#/components/schemas/Metadata' SendAmountRequest: type: object required: - asset - value description: >- An object containing information about the amount that will be used in the operation. properties: asset: type: string description: The name of the asset used in the operation. value: type: string description: >- The amount that will be sent. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. SendShareRequest: type: object description: >- If different accounts are part of the operation, this object will contain the information about the percentage used for each account. properties: percentage: type: string description: >- The percentage that will be shared. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. percentageOfPercentage: type: integer description: >- The percentage of the percentage that will be shared. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. DistributeAmountRequest: type: object required: - asset - value description: An object containing information about the amount used in the operation. properties: asset: type: string description: The name of the asset used in the operation. value: type: string description: >- The amount that will be received. **Important:** Use a dot (`.`) as the decimal separator — commas are not accepted. headers: XIdempotencyReplayed: description: >- Indicates whether the response was replayed from cache (`true`) or is a fresh response from a newly processed transaction (`false`). Always check this header to avoid processing the same transaction twice on your side. See [Retries and idempotency](/en/reference/retries-idempotency) for details. schema: type: boolean example: false examples: Error0073: value: code: '0073' title: Transaction Value Mismatch message: >- The values for the source, the destination, or both do not match the specified transaction amount. Please verify the values and try again. summary: Transaction Value Mismatch Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0105: value: code: '0105' title: Transaction Route Not Found message: >- The provided transaction route does not exist in our records. Please verify the transaction route and try again. summary: Transaction Route Not Found Error0084: value: code: '0084' title: Duplicate Idempotency Key message: >- The idempotency key '{{key}}' is already in use and the original request is still being processed. Please retry later using the same idempotency key. summary: Duplicate Idempotency Key Error0018: value: code: '0018' title: Insufficient Funds Error message: >- The transaction could not be completed due to insufficient funds in the account. Please add sufficient funds to your account and try again. summary: Insufficient Funds Error0019: value: code: '0019' title: Account Ineligibility Error message: >- One or more accounts listed in the transaction are not eligible to participate. Please review the account statuses and try again. summary: Account Ineligibility Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````