Skip to main content
POST
/
v0
/
ledgers
Create a Ledger
curl --request POST \
  --url https://api.sandbox.teal.dev/v0/ledgers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'teal-instance-id: <teal-instance-id>' \
  --data '
{
  "editable": true,
  "name": "<string>",
  "debit_credit": "debit",
  "financial_account_type": null,
  "parent_id": null,
  "report_cash_flow": false,
  "sort_code": "1400",
  "sub_type": "current_assets",
  "type": "asset"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "debit_credit": "debit",
  "editable": true,
  "is_required": true,
  "parent_id": null,
  "report_cash_flow": true,
  "sort_code": "<string>",
  "sub_type": "current_assets",
  "type": "asset",
  "created_at": "2023-11-07T05:31:56Z",
  "financial_account_type": "bank_account",
  "parent": "<unknown>"
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
teal-instance-id
string
required

The Teal instance ID

Query Parameters

​
expand
enum<string>[] | null

Comma-separated list of Ledger expand paths.

Available options:
parent,
parent.parent,
details

Body

application/json
​
editable
boolean
required

Whether line entries can be manually added or removed from the ledger.

Set to false if you control the source of truth for the ledger and want to restrict user changes, for example, if the ledger is for a bank account or a payments account you control (i.e. you are a neobank or using a Banking as a Service platform

​
name
string
required

The name of the ledger.

Teal does not enforce any other conventions or patterns on naming schemes; however, we recommend you use concise, descriptive names, especially for financial account ledgers.

​
debit_credit
enum<string> | null

Indicates if the ledger is a credit or debit ledger.

Required if financial_account_type is not specified.

Available options:
debit,
credit
Example:

"debit"

​
financial_account_type
enum<string> | null

Indicates that the ledger represents a real-world financial account.

If provided when creating a new ledger object, you do not need to provide debit_credit, type, sub_type, or report_cash_flow values as we will provide default values.

See the default parameters for financial account types.

Available options:
bank_account,
credit_card,
payments,
payroll,
loan,
prepaid_card,
accounts_receivable,
accounts_payable
Example:

null

​
parent_id
string | null

If the ledger is a child Ledger, the ID of the parent ledger object.

Example:

null

​
report_cash_flow
boolean | null

Whether Teal includes this ledger in the cash flow report.

Required if financial_account_type is not specified.

Example:

false

​
sort_code
string | null

Determines the display order in reports, ordered digit by digit, starting from the leftmost position. For example, 20010 will come before 3050.

Teal does not enforce any other conventions or patterns on sort codes. However, it is recommended to adopt a common convention such as starting all ledgers of the same type with the same number (assets start with 1, liabilities start with 2, etc.). The default CoA templates provided by Teal follow best practices for sort code numbering.

Required if financial_account_type is not specified.

Maximum string length: 20
Example:

"1400"

​
sub_type
enum<string> | null

Indicates similar characteristics and accounting treatment for a group of ledgers within a type.

Required if financial_account_type is not specified.

Available options:
current_assets,
non-current_assets,
transfers_between_accounts,
uncategorized_assets,
current_liabilities,
non-current_liabilities,
equity,
operating_revenues,
other_income,
cost_of_goods_sold,
operating_expenses,
other_expenses
Example:

"current_assets"

​
type
enum<string> | null

Indicates the purpose and location of the funds and value recorded in the ledger and which report it is included in: asset, liability and equity ledgers are displayed on the balance sheet; revenue and expenses are displayed on the income statement.

Required if financial_account_type is not specified.

Available options:
asset,
liability,
equity,
revenue,
expense
Example:

"asset"

Response

Successful Response

​
id
string
required

The unique ID of the object.

​
name
string
required

The name of the ledger.

​
debit_credit
enum<string>
required

Indicates if the ledger is a credit or debit ledger.

Available options:
debit,
credit
​
editable
boolean
required

Whether line entries can be manually added or removed from the ledger.

​
is_required
boolean
required

Indicates that the ledger is one of the four system ledgers required for Teal to work. In the default chart of accounts, these are named one of: Transfers Between Accounts, Opening Balance Retained Earnings, Uncategorized Cash Inflow, Uncategorized Cash Outflow. You can update the names of these to fit your needs.

​
parent_id
string | null
required

If the ledger is a child Ledger, the ID of the parent ledger object.

Example:

null

​
report_cash_flow
boolean
required

Whether Teal includes this ledger in the cash flow report.

​
sort_code
string
required

Determines the display order in reports, ordered digit by digit, starting from the leftmost position. For example, 20010 will come before 3050.

​
sub_type
enum<string>
required

Indicates similar characteristics and accounting treatment for a group of ledgers within a type.

Available options:
current_assets,
non-current_assets,
transfers_between_accounts,
uncategorized_assets,
current_liabilities,
non-current_liabilities,
equity,
operating_revenues,
other_income,
cost_of_goods_sold,
operating_expenses,
other_expenses
​
type
enum<string>
required

Indicates the purpose and location of the funds and value recorded in the ledger and which report it is included in: asset, liability and equity ledgers are displayed on the balance sheet; revenue and expenses are displayed on the income statement.

Available options:
asset,
liability,
equity,
revenue,
expense
​
created_at
string<date-time>
required

The datetime when the ledger was created.

​
financial_account_type
enum<string> | null

Indicates that the ledger represents a real-world financial account.

Available options:
bank_account,
credit_card,
payments,
payroll,
loan,
prepaid_card,
accounts_receivable,
accounts_payable
Example:

"bank_account"

​
parent
any | null

Expandable. If the ledger is a child ledger, the parent ledger object.