POST/accounts

Create a new account

Store a newly created account

Request bodyrequired

Field	Type	Description
`code`required	string max length: 36	Account code (must be unique within ledger)
`name`required	string max length: 255	Account name
`type`required	string enum: asset \| liability \| equity \| revenue \| expense
`category`required	string enum: system \| customer	Account category — system (internal/GL) or customer (end-user balance)
`normal_balance`	string enum: debit \| credit · nullable	Normal balance side (defaults based on type)
`parent_code`	string max length: 36 · nullable	Parent account code for hierarchical structure (must exist in same ledger)
`description`	string max length: 1000 · nullable
`is_active`	boolean default: true
`is_system`	boolean default: false	System accounts cannot be deleted
`metadata`	object nullable	Arbitrary structured metadata for the account
`enforce_balance_limits`	boolean default: false	When true, balance must stay between min_balance and max_balance
`min_balance`	string nullable	Lower balance limit as a major-unit decimal string. Required when enforce_balance_limits is true. Negative values are permitted for liability accounts.
`max_balance`	string nullable	Upper balance limit as a major-unit decimal string. Must be >= min_balance.

Responses

201Account created successfully

{
  "success": true,
  "data": {
    "id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "ledger_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "code": "1000",
    "name": "Cash",
    "type": "asset",
    "category": "system",
    "normal_balance": "debit",
    "balance": "1000.00",
    "is_active": true,
    "is_system": false,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

400Validation error

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

401Unauthenticated

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

403Forbidden

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

Examples

curl -X POST https://ledga.io/api/v1/accounts \
  -H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "1000",
  "name": "Cash",
  "type": "asset",
  "category": "system",
  "normal_balance": "debit",
  "is_active": true,
  "is_system": false,
  "enforce_balance_limits": false,
  "min_balance": "0.00",
  "max_balance": "10000.00"
}'

use Ledga\Api\LedgaClient;

$ledga = new LedgaClient('sk_xxxxxxxx_your_secret');

$account = $ledga->accounts->create([
    'code' => '1000',
    'name' => 'Cash',
    'type' => 'asset',
    'category' => 'system',
]);

← All endpoints