iotoms Docs

Create a ledger account

POST
/api/v1/accounting/accounts

Adds an account to your chart of accounts. Codes must be unique; a child must sit under a group account of the same type and inherits its report group and currency unless you set them.

How to use it

  1. Pick a parent group account from List ledger accounts, or plan a top-level account with its own reportGroup.
  2. Send a unique code, name and type matching the parent's type; set isGroup to true for a heading account.
  3. The account is created active, inheriting the parent's report group and currency unless you set them.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
code*string

Unique account code: starts with a letter or digit, then letters, digits, dot, underscore or hyphen; up to 30 characters.

name*string

Display name of the account. Required.

type*string

Account class: ASSET, LIABILITY, EQUITY, REVENUE or EXPENSE. Must match the parent's type when parentId is set.

Value in"ASSET""LIABILITY""EQUITY""REVENUE""EXPENSE"
reportGroup?|

Statement section, e.g. CASH_AND_BANK or DIRECT_INCOME; must suit the type. Required for a top-level account; otherwise defaults to the parent's.

Value in"DIRECT_INCOME""INDIRECT_INCOME""DIRECT_EXPENSE""INDIRECT_EXPENSE""CURRENT_ASSET""CASH_AND_BANK""RECEIVABLE""FIXED_ASSET""CURRENT_LIABILITY""PAYABLE""LONG_TERM_LIABILITY""EQUITY"null
parentId?|

ID of the group account to place this account under, from List ledger accounts. Omit for a top-level account.

Formatuuid
currency?|

Three-letter ISO currency code. Defaults to the parent's currency, otherwise the merchant's configured currency.

isGroup*boolean

True to create a group (heading) account that holds other accounts and never takes postings. Default false.

isControl*boolean

True to mark a control account that summarises a sub-ledger, such as receivables or payables. Default false.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The ledger account after the call.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/accounting/accounts' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "code": "string",  "name": "string",  "type": "ASSET",  "isGroup": true,  "isControl": true}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "code": "string",    "name": "string",    "type": "ASSET",    "reportGroup": "DIRECT_INCOME",    "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",    "currency": "string",    "isGroup": true,    "isControl": true,    "active": true,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}