> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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](/en/reference/midaz/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. ## OpenAPI ````yaml en/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts openapi: 3.1.0 info: title: Midaz Ledger API description: >- Complete API reference for Midaz Ledger services including organization management, ledger operations, assets, segments, portfolios, accounts, account types, transactions, operations, balances, operation routes, transaction routes, and metadata indexes. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API - name: Holders API - name: Instruments API - name: Billing Packages API - name: Packages API - name: Billing Calculation API - name: Estimation API - name: Encryption API - name: Protection API - name: Asset Rates API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts: post: tags: - Accounts API summary: Create an Account description: > 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](/en/reference/midaz/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. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' example: 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 responses: '201': description: >- Indicates that the request was successful and the response contains the expected data. content: application/json: schema: $ref: '#/components/schemas/CreateAccountResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0009: $ref: '#/components/examples/Error0009' Error0029: $ref: '#/components/examples/Error0029' Error0047: $ref: '#/components/examples/Error0047' Error0050: $ref: '#/components/examples/Error0050' Error0051: $ref: '#/components/examples/Error0051' Error0053: $ref: '#/components/examples/Error0053' Error0066: $ref: '#/components/examples/Error0066' Error0067: $ref: '#/components/examples/Error0067' Error0094: $ref: '#/components/examples/Error0094' headers: {} '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0034: $ref: '#/components/examples/Error0034' Error0035: $ref: '#/components/examples/Error0035' Error0036: $ref: '#/components/examples/Error0036' Error0037: $ref: '#/components/examples/Error0037' Error0038: $ref: '#/components/examples/Error0038' Error0109: $ref: '#/components/examples/Error0109' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0020: $ref: '#/components/examples/Error0020' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: The unique identifier of the Organization associated with the Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: The unique identifier of the associated Ledger. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid ContentType: name: Content-Type in: header description: >- The type of media of the resource. Recommended value is `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: A unique identifier used to trace and track each request. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > 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 ` schemas: CreateAccountRequest: type: object properties: assetCode: type: string maxLength: 100 description: >- 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](/en/reference/midaz/create-an-asset) endpoint. name: type: string description: The name of the Account. maxLength: 256 alias: type: string maxLength: 100 pattern: ^[a-zA-Z0-9@:_-]+$ description: >- 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. type: type: string maxLength: 256 description: >- 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](/en/reference/midaz/create-an-account-type). 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. blocked: type: boolean default: false description: Defines whether the account should start locked. parentAccountId: type: - string - 'null' description: >- The unique identifier of the parent Account, if this is a sub-account. format: uuid entityId: type: - string - 'null' maxLength: 256 description: The unique identifier of the Entity responsible for the Account. portfolioId: type: - string - 'null' description: The unique identifier of the associated Portfolio. format: uuid segmentId: type: - string - 'null' description: >- The unique identifier of the Segment which is used to cluster the Account. format: uuid status: $ref: '#/components/schemas/StatusOrganizationRequest' metadata: $ref: '#/components/schemas/Metadata' required: - assetCode - type CreateAccountResponse: type: object properties: id: type: string description: The unique identifier of the Account. format: uuid organizationId: type: string format: uuid description: The unique identifier of the Organization. ledgerId: type: string description: The unique identifier of the Ledger. format: uuid assetCode: type: string description: The code that identifies the Asset used in the Account. name: type: string description: The name of the Account. maxLength: 256 alias: type: string description: >- A unique, user-friendly identifier for the account. Used to reference the account in transactions and other operations. type: type: string description: Specifies the Account Type associated with the account. blocked: type: boolean default: false description: Defines whether the account should be blocked. parentAccountId: type: - string - 'null' format: uuid description: The unique identifier of the Parent Account. entityId: type: - string - 'null' description: The unique identifier of the Entity responsible for the Account. portfolioId: type: - string - 'null' description: The unique identifier of the associated Portfolio. format: uuid segmentId: type: - string - 'null' description: >- The unique identifier of the Segment which is used to cluster the Account. format: uuid status: $ref: '#/components/schemas/StatusOrganization' metadata: $ref: '#/components/schemas/Metadata' createdAt: type: string format: date-time description: Timestamp of creation (UTC). updatedAt: type: string format: date-time description: Timestamp of last update (UTC). deletedAt: type: - string - 'null' format: date-time description: Timestamp of soft deletion, if applicable (UTC). ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. entityType: type: string description: >- The type of entity the error relates to (e.g. organization, ledger, account, transaction). Optional. fields: type: object additionalProperties: true description: Additional information about the fields that caused the error. StatusOrganizationRequest: type: object description: >- An object containing information about the status. **Important**: If not provided, the default status will be 'ACTIVE'. properties: code: type: string maxLength: 100 description: The name of the status. description: type: - string - 'null' maxLength: 256 description: The description of the status. Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- 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. StatusOrganization: type: object description: An object containing information about the status. properties: code: type: string maxLength: 100 description: The name of the status. description: type: - string - 'null' maxLength: 256 description: The description of the status. examples: Error0009: summary: Missing Fields in Request value: code: '0009' title: Missing Fields in Request message: >- Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. fields: metadataKey: metadataKey is a required field Error0029: summary: Invalid Parent Account ID value: code: '0029' title: Invalid Parent Account ID message: >- The specified parent account ID does not exist. Please verify the ID is correct and try your request again. Error0047: summary: Bad Request value: code: '0047' title: Bad Request message: >- The server could not understand the request due to malformed syntax. Please check the listed fields and try again. Error0050: value: code: '0050' title: Invalid Metadata message: >- One or more metadata entries are invalid. Please ensure metadata keys and values follow the allowed format. summary: Invalid Metadata Error0051: value: code: '0051' title: Invalid Metadata Key message: >- A metadata key contains unsupported characters or exceeds length limits. Please correct the key and try again. summary: Invalid Metadata Key Error0053: value: code: '0053' title: Unexpected Fields in the Request message: >- The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. fields: '{{field}}': '{{value}}' summary: Unexpected Fields in the Request Error0066: summary: Invalid Account Type value: code: '0066' title: Invalid Account Type message: >- The provided 'type' is not valid. Accepted types are: deposit, savings, loans, marketplace, cerditCard or external. Please provide a valid type. Error0067: value: code: '0067' title: Invalid Metadata Nesting message: >- The metadata object cannot contain nested values. Please ensure that the value {{value}} is not nested and try again. summary: Invalid Metadata Nesting Error0094: value: code: '0094' title: Invalid Request Body message: >- The request body is invalid or could not be parsed. Please check JSON structure and field types. summary: Invalid Request Body Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0034: summary: Asset Code Not Found value: code: '0034' title: Asset Code Not Found message: >- The provided asset code does not exist in our records. Please verify the asset code and try again. Error0035: summary: Portfolio ID Not Found value: code: '0035' title: Portfolio ID Not Found message: >- The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again. Error0036: summary: Segment ID Not Found value: code: '0036' title: Segment ID Not Found message: >- The provided segment ID does not exist in our records. Please verify the segment ID and try again. Error0037: summary: Ledger ID Not Found value: code: '0037' title: Ledger ID Not Found message: >- The provided ledger ID does not exist in our records. Please verify the ledger ID and try again. Error0038: summary: Organization ID Not Found value: code: '0038' title: Organization ID Not Found message: >- The provided organization ID does not exist in our records. Please verify the organization ID and try again. Error0109: value: code: '0109' message: >- The account type you are trying to access does not exist or has been removed. title: Account Type Not Found Error summary: Account Type Not Found Error Error0020: summary: Alias Unavailability Error value: code: '0020' title: Alias Unavailability Error message: >- The alias {{alias}} is already in use. Please choose a different alias and try again. Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````