A journal is a dated set of debit and credit lines that balance. It is the main way to write to an entity's books.
POST /api/public/v1/entities/{entityId}/journals prosaic.journals.create(entityId, params)A journal with GST
This records a $100 office expense plus 15% GST, owed to a supplier. With taxMode: 'TAX_EXCLUSIVE', each line's amount is before GST, and Prosaic adds the GST when it posts.
const journal = await prosaic.journals.create(entityId, {
date: '2026-10-01',
narration: 'Stationery, supplier invoice 1042',
taxMode: 'TAX_EXCLUSIVE',
lines: [
{
entityAccountCode: '4030', // Office Expense
taxRateId: gstOnExpensesId, // NZ_GST_15_EXP
debit: '100.00',
description: 'Printer paper and toner',
},
{
entityAccountCode: '8220', // Accounts Payable
taxRateId: noGstId, // NZ_GST_0_NONE
credit: '115.00',
},
],
});curl -X POST https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/journals \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-10-01",
"narration": "Stationery, supplier invoice 1042",
"taxMode": "TAX_EXCLUSIVE",
"lines": [
{ "entityAccountCode": "4030", "taxRateId": "GST_ON_EXPENSES_RATE_ID", "debit": "100.00", "description": "Printer paper and toner" },
{ "entityAccountCode": "8220", "taxRateId": "NO_GST_RATE_ID", "credit": "115.00" }
]
}'When it posts, the journal has three lines: $100 to Office Expense, a generated $15 GST line to the entity's GST account, and $115 to Accounts Payable.
Request fields
| Field | Required | Notes |
|---|---|---|
date | Yes | YYYY-MM-DD, a calendar day in the entity's own timezone. |
narration | Yes | 1 to 300 characters. Put your own reference here; see avoiding double-posting. |
lines | Yes | The journal lines. A posted journal needs at least two lines with an amount. |
taxMode | No | NO_TAX, TAX_EXCLUSIVE or TAX_INCLUSIVE. Leaving it out behaves like NO_TAX. |
autoPost | No | Defaults to true, which posts the journal. false saves a draft. |
fileIds | No | Uploaded files to attach. See attachments. |
Each line:
| Field | Notes |
|---|---|
entityAccountCode | The account's code from the entity's chart of accounts. Required on a line with an amount. |
taxRateId | An id from the entity's taxRates[] (see Tax in NZ and AU). Required on a line with an amount. |
debit or credit | A decimal string such as "115.00" (numbers are accepted too). Zero or positive. Use one side per line. |
description | Optional, up to 200 characters. |
dimensionOptionIds | Optional tracking categories; see dimensions. |
Lines with nothing on either side are dropped. An unknown account code or tax rate ID is rejected with 400.
Amounts
- Send amounts as decimal strings and do your sums with a decimal library such as Decimal.js, not floating point.
- Never send a negative amount to flip a line's direction. A negative number is rejected, and in a string the minus sign is stripped, so
"-50.00"is read as50.00on the side you put it. Move the amount to the other side instead. - Strings are cleaned of currency formatting, so
"$1,000.00"is read as1000.00. Prefer plain digits anyway.
Balancing and GST
A posted journal must balance to within one cent. How the check counts GST depends on taxMode:
taxMode | Line amounts are | At posting |
|---|---|---|
NO_TAX | Final | Nothing is added. Debits must equal credits as sent. |
TAX_EXCLUSIVE | Before GST | For each line whose tax rate is above 0%, a GST line is added to the entity's GST account. Debits must equal credits once GST is added. |
TAX_INCLUSIVE | Including GST | GST is split out of each taxed line into a GST line, so the line keeps its net amount. Debits must equal credits as sent. |
So with TAX_INCLUSIVE, the example above would send "115.00" on both lines, and post as the same three lines.
Check the balance before you send. An unbalanced journal is refused when it posts, nothing is saved, and today the API reports it as 500 Failed to create journal rather than a 400.
Drafts and posted journals
- Posted (
autoPostleft out ortrue): the journal is in the ledger and the reports straight away. The response'sstatusisposted. - Draft (
autoPost: false): saved withstatusdraft, without the balance check and without GST lines. Drafts are not in the reports. Someone reviews and posts them in the Prosaic app; the API cannot post a draft.
Drafts are the simplest review step: your product writes drafts, and the customer's accountant posts them.
The response
Journal creation returns the journal itself, not a data envelope:
idis this version of the journal.logicalJournalIdidentifies the journal across versions. Voiding and attaching files take this ID, so store it.dateis an instant: the start of the journal's day in the entity's timezone, in UTC. A New Zealand journal dated2026-10-01comes back as2026-09-30T11:00:00.000Z.linesincludes any generated GST lines, each withentityAccountandtaxRate. Amounts are decimal strings.attachmentslists attached files.
Listing journals
for await (const journal of prosaic.journals.list(entityId, {
dateFrom: '2026-09-30', // the day before: dateFrom is compared with UTC midnight
dateTo: '2026-10-31',
})) {
console.log(journal.logicalJournalId, journal.narration, journal.status);
}GET /entities/{entityId}/journals returns manual journals, newest first, a page at a time (page, pageSize). It does not include journals Prosaic creates itself, such as bank reconciliations. The date filters compare against UTC midnight rather than the entity's day. In New Zealand and Australia that misses journals dated on dateFrom itself, so pass the day before. dateTo already includes its own day.
For every posted line, from every source, use the general ledger.
Voiding a journal
await prosaic.journals.void(entityId, journal.logicalJournalId!);curl -X PATCH https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/journals/YOUR_LOGICAL_JOURNAL_ID/void \
-H "Authorization: Bearer $PROSAIC_API_KEY"Only posted journals can be voided. Voiding marks the journal voided and posts a reversal on the same date. The reports then leave both out; the general ledger shows them when you pass includeVoided=true. Journals that belong to an invoice or record a payment cannot be voided this way (409); undo those through the invoice or the bank transaction.
There is no endpoint to edit a posted journal or to delete a draft. To correct a posted journal, void it and post a new one.
Attachments
Attach receipts, invoices and other evidence. First upload the file to the entity, then attach it, either when you create the journal or afterwards.
import { readFile } from 'node:fs/promises';
const bytes = await readFile('receipt-1042.pdf');
const upload = await prosaic.files.upload(
entityId,
new File([bytes], 'receipt-1042.pdf', { type: 'application/pdf' }),
);
// When creating the journal:
await prosaic.journals.create(entityId, {
...params,
fileIds: [upload.file.id],
});
// Or on an existing journal:
await prosaic.journals.attachFiles(entityId, logicalJournalId, {
fileIds: [upload.file.id],
});Uploads are multipart/form-data with a file field, up to 20 MB. Set the file's type: PDF, JPEG, PNG, GIF, WebP, CSV, plain text, Excel, Word and Outlook MSG are accepted, and anything else is refused with 415. files.list(entityId) lists files already on the entity.
Dimensions
Dimensions are tracking categories, such as Property or Department. dimensions.list(entityId) returns the entity's dimensions and their options. Tag a line with dimensionOptionIds, at most one option per dimension. Options from another entity, or two from the same dimension, are rejected with 400.
Change-sets
POST /entities/{entityId}/change-sets (prosaic.changeSets.create) records proposed writes (journals to post, bank transactions to reconcile) as a pending change-set instead of writing them. Nothing reaches the ledger until the set is approved, and resubmitting identical content returns the existing set.
A change-set's journal lines name accounts by entityAccountId and take amounts as numbers, unlike journals.create. Change-sets were built for AI agents, and today approval happens in Prosaic's own review tooling rather than in your workspace. For a review step that you and your customers' accountants control, use drafts.
