All API resources
Journals
Manual journals: post or draft them, list them, attach files and void them.
Base URL https://app.prosaic.works/api/public/v1. Every request needs an API key or access token; see the overview.
List manual journals
/api/public/v1/entities/{entityId}/journalsSDK: prosaic.journals.list(entityId, params)
Returns paginated manual journals for the specified entity with optional date range filtering. Requires API key authentication and entity access. Only returns journals of type MANUAL (excludes automatic and reversal journals).
Path parameters
entityIdstringrequired
Query parameters
pageintegerPage number (starts at 1)
Default:
1pageSizeintegerNumber of items per page
Default:
20dateFromstring (date)Start date for filtering journals (ISO 8601 format)
dateTostring (date)End date for filtering journals (ISO 8601 format)
Responses
200 Successful response
dataarray of objectsrequiredShow 13 child attributesHide child attributes
logicalJournalIdstringrequirednullablepostedAtstring (date-time)requirednullablepostedBystringrequirednullableposterobjectnullableShow 5 child attributesHide child attributes
idstringrequiredemailstringrequirednamestringrequirednullabletradingNamestringrequirednullablecreatedAtstring (date-time)required
linesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredjournalIdstringrequiredparentIdstringrequirednullableentityAccountIdstringrequiredlineNumbernumberrequiredtypestringrequireddescriptionstringrequirednullablecreditstringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
debitstringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
taxRateIdstringrequirednullableentityAccountobjectrequiredShow 3 child attributesHide child attributes
idstringrequiredcodestringrequirednamestringrequired
taxRateobjectrequirednullableShow 5 child attributesHide child attributes
idstringrequiredcodestringrequirednamestringrequireddescriptionstringrequirednullableratestringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
idstringrequirednarrationstringrequireddatestring (date-time)requiredstatusstringrequiredtypestringrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)requiredreconciliationsarray of objectsShow 1 child attributeHide child attributes
bankTransactionobjectrequiredShow 3 child attributesHide child attributes
idstringrequireddescriptionstringrequiredmerchantobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequirednamestringrequired
paginationobjectrequiredShow 6 child attributesHide child attributes
currentPagenumberrequiredpageSizenumberrequiredtotalCountnumberrequiredtotalPagesnumberrequiredhasNextPagebooleanrequiredhasPreviousPagebooleanrequired
400Bad request - missing or invalid parameters401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity
const page = await prosaic.journals.list(entityId);curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals \
-H "Authorization: Bearer $PROSAIC_API_KEY"Create a manual journal
/api/public/v1/entities/{entityId}/journalsSDK: prosaic.journals.create(entityId, params)
Creates a new manual journal in either draft or posted status. By default, journals are automatically posted (status=POSTED).
Set autoPost: false to create in draft status (status=DRAFT), which allows for review before posting.
The journal must have balanced debits and credits. Lines are validated against the entity's chart of accounts and tax rates. Requires API key authentication and entity access.
Prerequisites — Finding Tax Codes and Account Codes
Before creating a journal, you need two pieces of information:
- Account codes: Retrieve the entity's chart of accounts via
GET /api/public/v1/entities/{entityId}/charts. Use the accountcodefield (e.g., "2030") as theentityAccountCodein journal lines. - Tax rate IDs: Retrieve the entity's tax rates via
GET /api/public/v1/entities(filter byentityId). Use thetaxRates[].idfield as thetaxRateIdin journal lines. Common tax codes include GST15, EXEMPT, and ZERO.
Dimensions (optional)
Lines can be tagged with dimensions (tracking categories such as Property or Department) by passing
dimensionOptionIds on each line — an array of dimension option UUIDs, at most one option per
dimension. Retrieve the entity's dimensions and option ids via
GET /api/public/v1/entities/{entityId}/dimensions. Options must belong to the entity;
unknown option ids or two options from the same dimension are rejected with a 400. Tagged lines
drive the dimension filter and "Segment by" columns on financial reports.
Path parameters
entityIdstringrequired
Request body
application/json
narrationstringrequireddatestringrequiredlinesarray of objectsrequiredShow 8 child attributesHide child attributes
entityAccountCodestringentityAccountNamestringtaxRateNamestringdescriptionstringcreditstring | numberdebitstring | numbertaxRateIdstringdimensionOptionIdsarray of strings
editReasonstringtaxModestringOne of:
NO_TAX,TAX_INCLUSIVE,TAX_EXCLUSIVEfileIdsarray of stringsautoPostboolean
Responses
200 Successful response
logicalJournalIdstringrequirednullablepostedAtstring (date-time)requirednullablepostedBystringrequirednullableposterobjectnullableShow 5 child attributesHide child attributes
idstringrequiredemailstringrequirednamestringrequirednullabletradingNamestringrequirednullablecreatedAtstring (date-time)required
linesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredjournalIdstringrequiredparentIdstringrequirednullableentityAccountIdstringrequiredlineNumbernumberrequiredtypestringrequireddescriptionstringrequirednullablecreditstringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
debitstringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
taxRateIdstringrequirednullableentityAccountobjectrequiredShow 3 child attributesHide child attributes
idstringrequiredcodestringrequirednamestringrequired
taxRateobjectrequirednullableShow 5 child attributesHide child attributes
idstringrequiredcodestringrequirednamestringrequireddescriptionstringrequirednullableratestringrequiredExact decimal serialized as a string. Use Decimal.js for arithmetic.
idstringrequirednarrationstringrequireddatestring (date-time)requiredstatusstringrequiredtypestringrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)requiredreconciliationsarray of objectsShow 1 child attributeHide child attributes
bankTransactionobjectrequiredShow 3 child attributesHide child attributes
idstringrequireddescriptionstringrequiredmerchantobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequirednamestringrequired
400Bad request - validation failed, invalid account codes, an unbalanced journal, or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity404Not found - Entity not found500Internal server error
const result = await prosaic.journals.create(entityId, {
date: '2026-04-01',
narration: 'Daily POS takings',
taxMode: 'TAX_INCLUSIVE',
lines: [
{
entityAccountCode: 'BANK_ACCOUNT_CODE',
taxRateId: 'NO_GST_TAX_RATE_ID',
debit: '1150.00',
},
{
entityAccountCode: 'SALES_ACCOUNT_CODE',
taxRateId: 'GST_15_TAX_RATE_ID',
credit: '1150.00',
},
],
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-04-01",
"narration": "Daily POS takings",
"taxMode": "TAX_INCLUSIVE",
"lines": [
{
"entityAccountCode": "BANK_ACCOUNT_CODE",
"taxRateId": "NO_GST_TAX_RATE_ID",
"debit": "1150.00"
},
{
"entityAccountCode": "SALES_ACCOUNT_CODE",
"taxRateId": "GST_15_TAX_RATE_ID",
"credit": "1150.00"
}
]
}'Create several manual journals at once
/api/public/v1/entities/{entityId}/journals/bulkSDK: prosaic.journals.createBulk(entityId, params)
Creates up to 100 manual journals, with at most 1,000 lines between them, in one transaction:
either every journal is recorded or none is. Each journal takes the same fields as
POST /api/public/v1/entities/{entityId}/journals, including dimensions and fileIds.
autoPost is required and applies to the whole set. true posts every journal to the ledger,
and false saves every journal as a draft.
Retrying safely
Send an idempotencyKey to make a retry safe. A repeat of the same request with the same key
returns the journals it created, with replayed: true and status 200, and records nothing new.
A replay shows each journal's current status, which may have changed since it was created.
The same key with different journals is refused with a 409. Without a key, a retry after a
timeout can record the whole set twice.
Fixing a rejected set
A 422 lists problems by each journal's position in journals, counting from 0. Nothing was
recorded, so fix them and send the whole set again.
Path parameters
entityIdstringrequired
Request body
application/json
autoPostbooleanrequiredjournalsarray of objectsrequiredShow 5 child attributesHide child attributes
datestringrequirednarrationstringrequiredlinesarray of objectsrequiredShow 8 child attributesHide child attributes
entityAccountCodestringentityAccountNamestringtaxRateNamestringdescriptionstringcreditstring | numberdebitstring | numbertaxRateIdstringdimensionOptionIdsarray of strings
taxModestringOne of:
NO_TAX,TAX_INCLUSIVE,TAX_EXCLUSIVEfileIdsarray of strings
idempotencyKeystring
Responses
200 Successful response
replayedbooleanrequireddataarray of objectsrequiredShow 5 child attributesHide child attributes
idstringrequiredlogicalJournalIdstringrequirednullablenarrationstringrequirednullabledatestring (date-time)requiredstatusstringrequired
metaobjectShow 1 child attributeHide child attributes
countnumberrequired
201 Successful response
replayedbooleanrequireddataarray of objectsrequiredShow 5 child attributesHide child attributes
idstringrequiredlogicalJournalIdstringrequirednullablenarrationstringrequirednullabledatestring (date-time)requiredstatusstringrequired
metaobjectShow 1 child attributeHide child attributes
countnumberrequired
400The request is malformed, or a taxed journal needs a GST account the entity lacks (SYSTEM_ACCOUNT_VALIDATION). Nothing was recorded.401Unauthorized - Invalid or missing API key404Not found - Entity not found or access denied409This idempotency key was already used for different journals (IDEMPOTENCY_KEY_REUSED)422One or more journals can't be recorded (JOURNALS_REJECTED); `details.problems` lists each with its index. Nothing was recorded.500Internal server error
const { data } = await prosaic.journals.createBulk(entityId, {
autoPost: true,
journals: [
{
date: '2026-04-01',
narration: 'Office supplies',
lines: [
{},
],
},
],
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/bulk \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"autoPost": true,
"journals": [
{
"date": "2026-04-01",
"narration": "Office supplies",
"lines": [
{}
]
}
]
}'Attach files to an existing journal
/api/public/v1/entities/{entityId}/journals/{journalId}/attachmentsSDK: prosaic.journals.attachFiles(entityId, journalId, params)
Attaches one or more previously uploaded files to a journal. Files must already be uploaded to the entity via the file upload endpoint. Requires API key authentication and entity access.
Path parameters
entityIdstringrequiredjournalIdstringrequired
Request body
application/json
fileIdsarray of stringsrequired
Responses
200 Successful response
successbooleanrequiredOne of:
trueattachmentsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredfileIdstringrequiredcreatedAtstring (date-time)required
400Bad request - validation failed or files not found401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity404Not found - Journal not found500Internal server error
const result = await prosaic.journals.attachFiles(entityId, journalId, {
fileIds: ['FILE_ID'],
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/attachments \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileIds": [
"FILE_ID"
]
}'Void a journal
/api/public/v1/entities/{entityId}/journals/{journalId}/voidSDK: prosaic.journals.void(entityId, journalId)
Voids a posted journal for the specified entity. Only posted journals can be voided. Requires API key authentication and entity access.
Path parameters
entityIdstringrequiredjournalIdstringrequired
Responses
200 Successful response
originalJournalobjectrequiredShow 4 child attributesHide child attributes
idstringrequiredstatusstringrequiredvoidedAtstring (date-time)requirednullablevoidedBystringrequirednullable
reversalJournalobjectrequiredShow 5 child attributesHide child attributes
idstringrequiredstatusstringrequiredpostedAtstring (date-time)requiredpostedBystringrequiredvoidedJournalIdstringrequired
voidedAtstring (date-time)required
400Journal is not in a voidable state404Journal not found500Internal server error
const result = await prosaic.journals.void(entityId, journalId);curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/void \
-H "Authorization: Bearer $PROSAIC_API_KEY"