v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Accounts API

Create an Account

Use this endpoint to create an Account in Midaz. You can create as many accounts as necessary to structure your ledger, but each request creates only one account at a time.

Important: Before creating an Account, ensure the corresponding Asset already exists. Use the Create an Asset endpoint to register it if needed.

If you have previously defined Account Types, make sure they are properly configured before account creation. We recommend either recreating existing accounts or updating them to include the correct type before enabling the Account Type validation feature — this helps prevent validation errors and ensures compliance with your accounting structure.

Note: the type value external is reserved for system-managed external accounts and is rejected on input.

post/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts

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>

Request body

assetCodestring required

The code that identifies the Asset used in the Account. Important: Must be an Asset that you've already created using the Create an Asset endpoint.

namestring

The name of the Account.

aliasstring

A unique, user-friendly identifier for the account. Used to reference the account in transactions and other operations. If not provided, the system will use the account's ID as the alias. Note: the alias must not contain the reserved prefix @external/, which is reserved for system-managed external accounts.

typestring required

Specifies the Account Type associated with the account. This field is required. Important: When Account Type validation is enabled for your Organization and Ledger, the value must match an existing keyValue defined in your Account Types configuration. When validation is disabled (default behavior), the field is still required but accepts any free-form string without validation. The value external is reserved and rejected on input.

blockedboolean

Defines whether the account should start locked.

parentAccountIdstring uuid nullable

The unique identifier of the parent Account, if this is a sub-account.

entityIdstring nullable

The unique identifier of the Entity responsible for the Account.

portfolioIdstring uuid nullable

The unique identifier of the associated Portfolio.

segmentIdstring uuid nullable

The unique identifier of the Segment which is used to cluster the Account.

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.

Response

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

idstring uuid

The unique identifier of the Account.

organizationIdstring uuid

The unique identifier of the Organization.

ledgerIdstring uuid

The unique identifier of the Ledger.

assetCodestring

The code that identifies the Asset used in the Account.

namestring

The name of the Account.

aliasstring

A unique, user-friendly identifier for the account. Used to reference the account in transactions and other operations.

typestring

Specifies the Account Type associated with the account.

blockedboolean

Defines whether the account should be blocked.

parentAccountIdstring uuid nullable

The unique identifier of the Parent Account.

entityIdstring nullable

The unique identifier of the Entity responsible for the Account.

portfolioIdstring uuid nullable

The unique identifier of the associated Portfolio.

segmentIdstring uuid nullable

The unique identifier of the Segment which is used to cluster the Account.

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'.

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).