Open a holder-owned account (with optional instrument)

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alias": "@treasury_checking",
  "assetCode": "USD",
  "blocked": true,
  "entityId": "EXT-ACC-12345",
  "metadata": {},
  "name": "Corporate Checking Account",
  "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": {
    "code": "ACTIVE",
    "description": "Active status"
  },
  "type": "deposit",
  "bankingDetails": {
    "account": "123450",
    "bankId": "12345",
    "branch": "0001",
    "closingDate": "2025-12-31",
    "countryCode": "US",
    "iban": "US12345678901234567890",
    "openingDate": "2025-01-01",
    "type": "CACC"
  },
  "regulatoryFields": {
    "accountType": "DEPOSIT",
    "participantDocument": "12345678912345"
  },
  "relatedParties": [
    {
      "document": "12345678900",
      "name": "John Smith",
      "role": "PRIMARY_HOLDER",
      "startDate": "2025-01-01",
      "endDate": "2026-01-01",
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "skip": {
    "holder": false
  }
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"alias\": \"@treasury_checking\",\n  \"assetCode\": \"USD\",\n  \"blocked\": true,\n  \"entityId\": \"EXT-ACC-12345\",\n  \"metadata\": {},\n  \"name\": \"Corporate Checking Account\",\n  \"parentAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"portfolioId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"segmentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Active status\"\n  },\n  \"type\": \"deposit\",\n  \"bankingDetails\": {\n    \"account\": \"123450\",\n    \"bankId\": \"12345\",\n    \"branch\": \"0001\",\n    \"closingDate\": \"2025-12-31\",\n    \"countryCode\": \"US\",\n    \"iban\": \"US12345678901234567890\",\n    \"openingDate\": \"2025-01-01\",\n    \"type\": \"CACC\"\n  },\n  \"regulatoryFields\": {\n    \"accountType\": \"DEPOSIT\",\n    \"participantDocument\": \"12345678912345\"\n  },\n  \"relatedParties\": [\n    {\n      \"document\": \"12345678900\",\n      \"name\": \"John Smith\",\n      \"role\": \"PRIMARY_HOLDER\",\n      \"startDate\": \"2025-01-01\",\n      \"endDate\": \"2026-01-01\",\n      \"id\": \"00000000-0000-0000-0000-000000000000\"\n    }\n  ],\n  \"skip\": {\n    \"holder\": false\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alias: '@treasury_checking',
    assetCode: 'USD',
    blocked: true,
    entityId: 'EXT-ACC-12345',
    metadata: {},
    name: 'Corporate Checking Account',
    parentAccountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    portfolioId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    segmentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: {code: 'ACTIVE', description: 'Active status'},
    type: 'deposit',
    bankingDetails: {
      account: '123450',
      bankId: '12345',
      branch: '0001',
      closingDate: '2025-12-31',
      countryCode: 'US',
      iban: 'US12345678901234567890',
      openingDate: '2025-01-01',
      type: 'CACC'
    },
    regulatoryFields: {accountType: 'DEPOSIT', participantDocument: '12345678912345'},
    relatedParties: [
      {
        document: '12345678900',
        name: 'John Smith',
        role: 'PRIMARY_HOLDER',
        startDate: '2025-01-01',
        endDate: '2026-01-01',
        id: '00000000-0000-0000-0000-000000000000'
      }
    ],
    skip: {holder: false}
  })
};

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

import requests

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

payload = {
    "alias": "@treasury_checking",
    "assetCode": "USD",
    "blocked": True,
    "entityId": "EXT-ACC-12345",
    "metadata": {},
    "name": "Corporate Checking Account",
    "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": {
        "code": "ACTIVE",
        "description": "Active status"
    },
    "type": "deposit",
    "bankingDetails": {
        "account": "123450",
        "bankId": "12345",
        "branch": "0001",
        "closingDate": "2025-12-31",
        "countryCode": "US",
        "iban": "US12345678901234567890",
        "openingDate": "2025-01-01",
        "type": "CACC"
    },
    "regulatoryFields": {
        "accountType": "DEPOSIT",
        "participantDocument": "12345678912345"
    },
    "relatedParties": [
        {
            "document": "12345678900",
            "name": "John Smith",
            "role": "PRIMARY_HOLDER",
            "startDate": "2025-01-01",
            "endDate": "2026-01-01",
            "id": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "skip": { "holder": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "account": {
    "alias": "@treasury_checking",
    "assetCode": "USD",
    "blocked": true,
    "closedAt": "2021-01-01T00:00:00Z",
    "createdAt": "2021-01-01T00:00:00Z",
    "deletedAt": "2021-01-01T00:00:00Z",
    "entityId": "EXT-ACC-12345",
    "holderCheckSkipped": false,
    "holderId": "00000000-0000-0000-0000-000000000000",
    "id": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "name": "Corporate Checking Account",
    "organizationId": "00000000-0000-0000-0000-000000000000",
    "parentAccountId": "00000000-0000-0000-0000-000000000000",
    "portfolioId": "00000000-0000-0000-0000-000000000000",
    "segmentId": "00000000-0000-0000-0000-000000000000",
    "status": {
      "code": "ACTIVE",
      "description": "Active status"
    },
    "type": "deposit",
    "updatedAt": "2021-01-01T00:00:00Z",
    "metadata": {}
  },
  "instrument": {
    "accountId": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2025-01-01T00:00:00Z",
    "deletedAt": "2025-01-01T00:00:00Z",
    "holderId": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "updatedAt": "2025-01-01T00:00:00Z",
    "bankingDetails": {
      "account": "123450",
      "bankId": "12345",
      "branch": "0001",
      "closingDate": "2025-12-31",
      "countryCode": "US",
      "iban": "US12345678901234567890",
      "openingDate": "2025-01-01",
      "type": "CACC"
    },
    "document": "12345678900",
    "id": "00000000-0000-0000-0000-000000000000",
    "metadata": {},
    "regulatoryFields": {
      "accountType": "DEPOSIT",
      "participantDocument": "12345678912345"
    },
    "relatedParties": [
      {
        "document": "12345678900",
        "name": "John Smith",
        "role": "PRIMARY_HOLDER",
        "startDate": "2025-01-01",
        "endDate": "2026-01-01",
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "type": "NATURAL_PERSON"
  },
  "instrumentError": {
    "reason": "0001",
    "status": "FAILED"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

POST

organizations

{organization_id}

ledgers

{ledger_id}

holders

{holder_id}

accounts

Open a holder-owned account (with optional instrument)

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alias": "@treasury_checking",
  "assetCode": "USD",
  "blocked": true,
  "entityId": "EXT-ACC-12345",
  "metadata": {},
  "name": "Corporate Checking Account",
  "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": {
    "code": "ACTIVE",
    "description": "Active status"
  },
  "type": "deposit",
  "bankingDetails": {
    "account": "123450",
    "bankId": "12345",
    "branch": "0001",
    "closingDate": "2025-12-31",
    "countryCode": "US",
    "iban": "US12345678901234567890",
    "openingDate": "2025-01-01",
    "type": "CACC"
  },
  "regulatoryFields": {
    "accountType": "DEPOSIT",
    "participantDocument": "12345678912345"
  },
  "relatedParties": [
    {
      "document": "12345678900",
      "name": "John Smith",
      "role": "PRIMARY_HOLDER",
      "startDate": "2025-01-01",
      "endDate": "2026-01-01",
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "skip": {
    "holder": false
  }
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"alias\": \"@treasury_checking\",\n  \"assetCode\": \"USD\",\n  \"blocked\": true,\n  \"entityId\": \"EXT-ACC-12345\",\n  \"metadata\": {},\n  \"name\": \"Corporate Checking Account\",\n  \"parentAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"portfolioId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"segmentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": {\n    \"code\": \"ACTIVE\",\n    \"description\": \"Active status\"\n  },\n  \"type\": \"deposit\",\n  \"bankingDetails\": {\n    \"account\": \"123450\",\n    \"bankId\": \"12345\",\n    \"branch\": \"0001\",\n    \"closingDate\": \"2025-12-31\",\n    \"countryCode\": \"US\",\n    \"iban\": \"US12345678901234567890\",\n    \"openingDate\": \"2025-01-01\",\n    \"type\": \"CACC\"\n  },\n  \"regulatoryFields\": {\n    \"accountType\": \"DEPOSIT\",\n    \"participantDocument\": \"12345678912345\"\n  },\n  \"relatedParties\": [\n    {\n      \"document\": \"12345678900\",\n      \"name\": \"John Smith\",\n      \"role\": \"PRIMARY_HOLDER\",\n      \"startDate\": \"2025-01-01\",\n      \"endDate\": \"2026-01-01\",\n      \"id\": \"00000000-0000-0000-0000-000000000000\"\n    }\n  ],\n  \"skip\": {\n    \"holder\": false\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alias: '@treasury_checking',
    assetCode: 'USD',
    blocked: true,
    entityId: 'EXT-ACC-12345',
    metadata: {},
    name: 'Corporate Checking Account',
    parentAccountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    portfolioId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    segmentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: {code: 'ACTIVE', description: 'Active status'},
    type: 'deposit',
    bankingDetails: {
      account: '123450',
      bankId: '12345',
      branch: '0001',
      closingDate: '2025-12-31',
      countryCode: 'US',
      iban: 'US12345678901234567890',
      openingDate: '2025-01-01',
      type: 'CACC'
    },
    regulatoryFields: {accountType: 'DEPOSIT', participantDocument: '12345678912345'},
    relatedParties: [
      {
        document: '12345678900',
        name: 'John Smith',
        role: 'PRIMARY_HOLDER',
        startDate: '2025-01-01',
        endDate: '2026-01-01',
        id: '00000000-0000-0000-0000-000000000000'
      }
    ],
    skip: {holder: false}
  })
};

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

import requests

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

payload = {
    "alias": "@treasury_checking",
    "assetCode": "USD",
    "blocked": True,
    "entityId": "EXT-ACC-12345",
    "metadata": {},
    "name": "Corporate Checking Account",
    "parentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "portfolioId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "segmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": {
        "code": "ACTIVE",
        "description": "Active status"
    },
    "type": "deposit",
    "bankingDetails": {
        "account": "123450",
        "bankId": "12345",
        "branch": "0001",
        "closingDate": "2025-12-31",
        "countryCode": "US",
        "iban": "US12345678901234567890",
        "openingDate": "2025-01-01",
        "type": "CACC"
    },
    "regulatoryFields": {
        "accountType": "DEPOSIT",
        "participantDocument": "12345678912345"
    },
    "relatedParties": [
        {
            "document": "12345678900",
            "name": "John Smith",
            "role": "PRIMARY_HOLDER",
            "startDate": "2025-01-01",
            "endDate": "2026-01-01",
            "id": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "skip": { "holder": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "account": {
    "alias": "@treasury_checking",
    "assetCode": "USD",
    "blocked": true,
    "closedAt": "2021-01-01T00:00:00Z",
    "createdAt": "2021-01-01T00:00:00Z",
    "deletedAt": "2021-01-01T00:00:00Z",
    "entityId": "EXT-ACC-12345",
    "holderCheckSkipped": false,
    "holderId": "00000000-0000-0000-0000-000000000000",
    "id": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "name": "Corporate Checking Account",
    "organizationId": "00000000-0000-0000-0000-000000000000",
    "parentAccountId": "00000000-0000-0000-0000-000000000000",
    "portfolioId": "00000000-0000-0000-0000-000000000000",
    "segmentId": "00000000-0000-0000-0000-000000000000",
    "status": {
      "code": "ACTIVE",
      "description": "Active status"
    },
    "type": "deposit",
    "updatedAt": "2021-01-01T00:00:00Z",
    "metadata": {}
  },
  "instrument": {
    "accountId": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2025-01-01T00:00:00Z",
    "deletedAt": "2025-01-01T00:00:00Z",
    "holderId": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "updatedAt": "2025-01-01T00:00:00Z",
    "bankingDetails": {
      "account": "123450",
      "bankId": "12345",
      "branch": "0001",
      "closingDate": "2025-12-31",
      "countryCode": "US",
      "iban": "US12345678901234567890",
      "openingDate": "2025-01-01",
      "type": "CACC"
    },
    "document": "12345678900",
    "id": "00000000-0000-0000-0000-000000000000",
    "metadata": {},
    "regulatoryFields": {
      "accountType": "DEPOSIT",
      "participantDocument": "12345678912345"
    },
    "relatedParties": [
      {
        "document": "12345678900",
        "name": "John Smith",
        "role": "PRIMARY_HOLDER",
        "startDate": "2025-01-01",
        "endDate": "2026-01-01",
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "type": "NATURAL_PERSON"
  },
  "instrumentError": {
    "reason": "0001",
    "status": "FAILED"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

Authorization

string

Bearer token (forwarded to the composed account-create use case)

X-Idempotency

string

Idempotency key to safely retry the composition; a retry with the same key returns the original response, a partial 201 with its instrumentError included, as first answered. Without it no idempotency slot is reserved

X-TTL

string

Idempotency slot TTL in seconds (default 300)

Path Parameters

organization_id

string

required

Organization ID (UUID)

ledger_id

string

required

Ledger ID (UUID)

holder_id

string

required

Holder ID (UUID)

Body

application/json

alias

string | null

required

Maximum string length: 100

Example:

"@treasury_checking"

assetCode

string

required

Maximum string length: 100

Example:

"USD"

blocked

boolean | null

required

entityId

string | null

required

Maximum string length: 256

Example:

"EXT-ACC-12345"

metadata

object

required

Show child attributes

name

string

required

Maximum string length: 256

Example:

"Corporate Checking Account"

parentAccountId

string<uuid> | null

required

portfolioId

string<uuid> | null

required

segmentId

string<uuid> | null

required

status

object

required

Show child attributes

type

string

required

Example:

"deposit"

bankingDetails

object

Show child attributes

regulatoryFields

object

Show child attributes

skip

object

Show child attributes

Response

Created

account

object

required

Show child attributes

instrument

object

required

Show child attributes

instrumentError

object

Show child attributes

Getting started

Core

CRM

Fees

Error handling

Events

Open a holder-owned account (with optional instrument)

Authorizations

Headers

Path Parameters

Body

Response