---
title: "Create a Ledger"
method: POST
path: "/v1/organizations/{organization_id}/ledgers"
tags: ["Ledgers API"]
---

# Create a Ledger

`POST /v1/organizations/{organization_id}/ledgers`

## Request

- Base URL: `https://identity.sandbox.lerian.net`
- URL: `https://identity.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers`
- Auth: none required
- TypeScript: <https://skmtc.dev/lerian/apis/identity-plugin/docs/v1/organizations/:organization_id/ledgers/post.ts> (a function with typed inputs; its response is checked against the schema)

Use this endpoint to create a Ledger.

## Path parameters

- `organization_id` string, uuid, required

## Headers

- `Content-Type` string
- `X-Request-Id` string, uuid
- `Authorization` string

## Request body

- CreateLedgerRequest
  - `name` string, required: The name of the Ledger.
  - `status` StatusOrganizationRequest: An object containing information about the status. **Important**: If not provided, the default status will be 'ACTIVE'.
    - `code` string: The name of the status.
    - `description` string, nullable: The description of the status.
  - `metadata` Metadata: 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.
  - `settings` object: Optional dynamic configuration settings for the Ledger. When omitted, default values are applied (all validation flags disabled).
    - `accounting` object: Accounting-related settings for the Ledger.
      - `validateAccountType` boolean: When enabled, validates that account types match the rules defined in operation routes during transaction processing.
      - `validateRoutes` boolean: When enabled, every transaction in this Ledger must have an associated transaction route. Operations are also validated against their operation route rules.

## Response `201`

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

- CreateLedgerResponse
  - `id` string, uuid: The unique identifier of the Ledger.
  - `organizationId` string, uuid: The unique identifier of the Organization.
  - `name` string: The name of the Ledger.
  - `status` StatusOrganization: An object containing information about the status.
    - `code` string: The name of the status.
    - `description` string, nullable: The description of the status.
  - `metadata` Metadata: 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.
  - `settings` LedgerSettingsResponse: The current settings of a Ledger.
    - `accounting` object: Accounting-related settings for the Ledger.
      - `validateAccountType` boolean: When enabled, validates that account types match the rules defined in operation routes during transaction processing.
      - `validateRoutes` boolean: When enabled, every transaction in this Ledger must have an associated transaction route. Operations are also validated against their operation route rules.
  - `createdAt` string, date-time: Timestamp of creation (UTC).
  - `updatedAt` string, date-time: Timestamp of last update (UTC).
  - `deletedAt` string, date-time, nullable: Timestamp of soft deletion, if applicable (UTC).

## Other responses

- `400`
- `401`: Unauthorized
- `403`: Forbidden
- `404`
- `409`
- `500`: Internal Server Error

---

[API](https://skmtc.dev/lerian/apis/identity-plugin.md) - [All operations](https://skmtc.dev/lerian/apis/identity-plugin/llms.txt) - [OpenAPI document](https://skmtc.dev/lerian/apis/identity-plugin/revisions/25daba385532?raw)