Crear una Cuenta

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "assetCode": "BRL",
  "name": "Primary BRL Wallet",
  "alias": "@customer_brl_wallet",
  "type": "CHECKING",
  "status": {
    "code": "ACTIVE",
    "description": "Operational retail account for Pix and internal payments"
  },
  "metadata": {
    "bankCode": "341",
    "branchNumber": "0001",
    "accountNumber": "12345678-9",
    "accountPlan": "retail_personal_wallet",
    "dailyLimit": 50000
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ledgerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assetCode": "<string>",
  "name": "<string>",
  "alias": "<string>",
  "type": "<string>",
  "blocked": false,
  "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entityId": "<string>",
  "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<unknown>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

Crear una Cuenta

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 Crear un Activo 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.

POST

organizations

{organization_id}

ledgers

{ledger_id}

accounts

Crear una Cuenta

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "assetCode": "BRL",
  "name": "Primary BRL Wallet",
  "alias": "@customer_brl_wallet",
  "type": "CHECKING",
  "status": {
    "code": "ACTIVE",
    "description": "Operational retail account for Pix and internal payments"
  },
  "metadata": {
    "bankCode": "341",
    "branchNumber": "0001",
    "accountNumber": "12345678-9",
    "accountPlan": "retail_personal_wallet",
    "dailyLimit": 50000
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ledgerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assetCode": "<string>",
  "name": "<string>",
  "alias": "<string>",
  "type": "<string>",
  "blocked": false,
  "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entityId": "<string>",
  "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<unknown>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

Encabezados

Authorization

string

El token de autorización. Este encabezado es requerido si su entorno tiene el Access Manager habilitado.

Content-Type

string

requerido

El tipo de medio del recurso. Debe ser application/json.

X-Request-Id

string<uuid>

Un identificador único utilizado para rastrear y seguir cada solicitud.

Parámetros de ruta

organization_id

string

requerido

The unique identifier of the Organization associated with the Ledger.

ledger_id

string

requerido

The unique identifier of the associated Ledger.

Cuerpo

application/json

assetCode

string

requerido

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

type

string

requerido

Specifies the Account Type associated with the account. Important: When Account Type validation is enabled for your Organization and Ledger, this field becomes mandatory and must match an existing keyValue defined in your Account Types configuration. However, when validation is disabled (default behavior), this field is optional and accepts any free-form string without validation.

name

string

The name of the Account.

Maximum string length: 256

alias

string

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.

Maximum string length: 100

blocked

boolean

predeterminado:false

Defines whether the account should start locked.

parentAccountId

string<uuid> | null

The unique identifier of the Parent Account. If the account does not have a parent account, this field will be null.

entityId

string | null

The unique identifier of the Entity responsible for the Account.

portfolioId

string<uuid> | null

The unique identifier of the associated Portfolio.

segmentId

string<uuid> | null

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

status

object

An object containing information about the status. Important: If not provided, the default status will be 'ACTIVE'.

Mostrar atributos secundarios

metadata

object

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

Mostrar atributos secundarios

Respuesta

Indica que la solicitud fue exitosa y la respuesta contiene los datos esperados.

string<uuid>

El identificador único de la Cuenta.

organizationId

string<uuid>

The unique identifier of the Organization.

ledgerId

string<uuid>

El identificador único del Ledger.

assetCode

string

The code that identifies the Asset used in the Account.

name

string

The name of the Account.

Maximum string length: 256

alias

string

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

type

string

Specifies the Account Type associated with the account.

blocked

boolean

predeterminado:false

Defines whether the account should be blocked.

parentAccountId

string<uuid> | null

The unique identifier of the Parent Account.

entityId

string | null

The unique identifier of the Entity responsible for the Account.

portfolioId

string<uuid> | null

The unique identifier of the associated Portfolio.

segmentId

string<uuid> | null

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

status

any

metadata

object

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

Mostrar atributos secundarios

createdAt

string<date-time>

Timestamp of creation (UTC).

updatedAt

string<date-time>

Timestamp of last update (UTC).

deletedAt

string<date-time> | null

Timestamp of soft deletion, if applicable (UTC).

Eliminar un Tipo de Cuenta

Listar Cuentas

⌘I

Primeros pasos

Organizations API

Ledgers API

Assets API

Account Types API

Accounts API

Portfolios API

Segments API

Balances API

Transactions API

Operations API

Operation Routes API

Transaction Routes API

Metadata Indexes API

Manejo de errores

Crear una Cuenta

Encabezados

Parámetros de ruta

Cuerpo

Respuesta