Create an Account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "assetCode": "BRL",
  "name": "Customer BRL Account 1",
  "alias": "customer-brl-1",
  "type": "deposit",
  "status": {
    "code": "ACTIVE",
    "description": "Account Created"
  },
  "metadata": {
    "bankCode": "341",
    "branchNumber": "0001",
    "accountNumber": "12345678-9",
    "accountPlan": "retail_personal_wallet",
    "dailyLimit": 50000
  }
}
'

import requests

url = "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts"

payload = {
    "assetCode": "BRL",
    "name": "Customer BRL Account 1",
    "alias": "customer-brl-1",
    "type": "deposit",
    "status": {
        "code": "ACTIVE",
        "description": "Account Created"
    },
    "metadata": {
        "bankCode": "341",
        "branchNumber": "0001",
        "accountNumber": "12345678-9",
        "accountPlan": "retail_personal_wallet",
        "dailyLimit": 50000
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    assetCode: 'BRL',
    name: 'Customer BRL Account 1',
    alias: 'customer-brl-1',
    type: 'deposit',
    status: {code: 'ACTIVE', description: 'Account Created'},
    metadata: {
      bankCode: '341',
      branchNumber: '0001',
      accountNumber: '12345678-9',
      accountPlan: 'retail_personal_wallet',
      dailyLimit: 50000
    }
  })
};

fetch('https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assetCode' => 'BRL',
    'name' => 'Customer BRL Account 1',
    'alias' => 'customer-brl-1',
    'type' => 'deposit',
    'status' => [
        'code' => 'ACTIVE',
        'description' => 'Account Created'
    ],
    'metadata' => [
        'bankCode' => '341',
        'branchNumber' => '0001',
        'accountNumber' => '12345678-9',
        'accountPlan' => 'retail_personal_wallet',
        'dailyLimit' => 50000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts"

	payload := strings.NewReader("{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts")
  .header("Content-Type", "application/json")
  .body("{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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": {
    "code": "<string>",
    "description": "<string>"
  },
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

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

organizations

{organization_id}

ledgers

{ledger_id}

accounts

Create an Account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "assetCode": "BRL",
  "name": "Customer BRL Account 1",
  "alias": "customer-brl-1",
  "type": "deposit",
  "status": {
    "code": "ACTIVE",
    "description": "Account Created"
  },
  "metadata": {
    "bankCode": "341",
    "branchNumber": "0001",
    "accountNumber": "12345678-9",
    "accountPlan": "retail_personal_wallet",
    "dailyLimit": 50000
  }
}
'

import requests

url = "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts"

payload = {
    "assetCode": "BRL",
    "name": "Customer BRL Account 1",
    "alias": "customer-brl-1",
    "type": "deposit",
    "status": {
        "code": "ACTIVE",
        "description": "Account Created"
    },
    "metadata": {
        "bankCode": "341",
        "branchNumber": "0001",
        "accountNumber": "12345678-9",
        "accountPlan": "retail_personal_wallet",
        "dailyLimit": 50000
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    assetCode: 'BRL',
    name: 'Customer BRL Account 1',
    alias: 'customer-brl-1',
    type: 'deposit',
    status: {code: 'ACTIVE', description: 'Account Created'},
    metadata: {
      bankCode: '341',
      branchNumber: '0001',
      accountNumber: '12345678-9',
      accountPlan: 'retail_personal_wallet',
      dailyLimit: 50000
    }
  })
};

fetch('https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assetCode' => 'BRL',
    'name' => 'Customer BRL Account 1',
    'alias' => 'customer-brl-1',
    'type' => 'deposit',
    'status' => [
        'code' => 'ACTIVE',
        'description' => 'Account Created'
    ],
    'metadata' => [
        'bankCode' => '341',
        'branchNumber' => '0001',
        'accountNumber' => '12345678-9',
        'accountPlan' => 'retail_personal_wallet',
        'dailyLimit' => 50000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts"

	payload := strings.NewReader("{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts")
  .header("Content-Type", "application/json")
  .body("{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assetCode\": \"BRL\",\n  \"name\": \"Customer BRL Account 1\",\n  \"alias\": \"customer-brl-1\",\n  \"type\": \"deposit\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Account Created\"\n  },\n  \"metadata\": {\n    \"bankCode\": \"341\",\n    \"branchNumber\": \"0001\",\n    \"accountNumber\": \"12345678-9\",\n    \"accountPlan\": \"retail_personal_wallet\",\n    \"dailyLimit\": 50000\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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": {
    "code": "<string>",
    "description": "<string>"
  },
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

Headers

Content-Type

string

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

X-Request-Id

string<uuid>

A unique identifier used to trace and track each request.

Authorization

string

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>

Path Parameters

organization_id

string<uuid>

required

The unique identifier of the Organization associated with the Ledger.

ledger_id

string<uuid>

required

The unique identifier of the associated Ledger.

Body

application/json

assetCode

string

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.

Maximum string length: 100

type

string

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.

Maximum string length: 256

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. Note: the alias must not contain the reserved prefix @external/, which is reserved for system-managed external accounts.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9@:_-]+$

blocked

boolean

default:false

Defines whether the account should start locked.

parentAccountId

string<uuid> | null

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

entityId

string | null

The unique identifier of the Entity responsible for the Account.

Maximum string length: 256

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

Show child attributes

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

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.

Show child attributes

Response

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

string<uuid>

The unique identifier of the Account.

organizationId

string<uuid>

The unique identifier of the Organization.

ledgerId

string<uuid>

The unique identifier of the 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

default: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

object

An object containing information about the status.

Show child attributes

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

Show child attributes

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

Delete an Account Type

List Accounts

Getting started

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

Holders API

Instruments API

Billing Packages API

Packages API

Billing Calculation API

Estimation API

Encryption API

Protection API

Asset Rates API

Error handling

Fees Engine

Create an Account

Headers

Path Parameters

Body

Response