iotoms Docs

Create a journal entry

POST
/api/v1/accounting/journal-entries

Creates a double-entry journal entry with at least two lines, as a draft or posted straight away with the post flag. Idempotent on sourceSystem plus externalId: resending the same pair returns the existing entry, which makes retries and replays safe.

How to use it

  1. Take account IDs from List ledger accounts; use active, non-group accounts.
  2. Send effectiveAt, currency and at least two lines with positive amountMinor; debits must equal credits to post.
  3. Set sourceSystem and externalId so a retry returns the same entry instead of a duplicate.
  4. With post true the entry is posted at once and becomes read-only; its effectiveAt must fall in an open period (see List accounting periods). Otherwise it stays a DRAFT.

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
externalId?|

Optional reference from your system. With sourceSystem it makes the call idempotent: resending the same pair returns the existing entry.

sourceSystem?|

Name of the system the entry comes from. Defaults to MANUAL when omitted.

eventType?|

Optional business event label for the entry, for reporting and filtering.

effectiveAt*string

Accounting date of the entry (YYYY-MM-DD). To post, it must fall inside an open accounting period.

Formatdate
currency*string

Three-letter currency code, for example USD. Every line must use the same currency.

memo?|

Optional free-text description of the entry.

correlationId?|

Optional reference for linking related entries together.

metadata?|

Optional free-form text (for example a JSON string) stored with the entry and returned as sent.

post*boolean

false saves the entry as a DRAFT; true validates it and posts it to the ledger in the same call.

lines*array<>

At least two debit/credit lines. To post, total debits must equal total credits.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when it worked, ERROR when it failed.

message*string

Short human-readable message describing the outcome, for example "Vendor created". Do not parse it.

data?

The journal entry, including all of its lines.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/accounting/journal-entries' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "effectiveAt": "2019-08-24",  "currency": "string",  "post": true,  "lines": [    {      "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",      "direction": "DEBIT",      "amountMinor": 0    }  ]}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "externalId": "string",    "sourceSystem": "string",    "eventType": "string",    "effectiveAt": "2019-08-24",    "postedAt": "2019-08-24T14:15:22Z",    "periodId": "7cc85576-6d6b-4609-a8e6-020187b27a09",    "status": "DRAFT",    "currency": "string",    "memo": "string",    "reversalOfId": "91205805-6131-4e22-87c1-99e3bbb30d9b",    "correlationId": "string",    "metadata": "string",    "createdAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": 0,        "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",        "accountCode": "string",        "accountName": "string",        "direction": "DEBIT",        "amountMinor": 0,        "currency": "string"      }    ]  }}