This walks through the core loop: create an entity, post a balanced journal to it, and read the trial balance back. Each step is shown with the Node SDK and with curl.
Before you start
- A Prosaic workspace. Sign up at app.prosaic.works/signup. A new workspace starts on a 14-day trial, is set to New Zealand, and comes with a couple of demo entities you can ignore. For an Australian workspace, which is in early access, write to developer@prosaic.works.
- For the SDK: Node.js 22 or later, and the SDK installed from its tarball as described in Node SDK. It is not on npm yet.
- For curl: nothing else.
1. Create an API key
API keys are created in the Prosaic app by a workspace owner or admin.
- Go to Settings → Users.
- Find the user the key should act as (often yourself), open the Actions menu (⋯) and choose Manage API keys.
- Choose Create API Key, give it a name and an expiry, and copy the key. It starts with
prsk_and is shown only once.
Keep it in your server environment:
export PROSAIC_API_KEY="prsk_..."A key acts as its user, with that user's access. Authentication covers the details, including OAuth.
2. Check the key works
GET /me returns the user the key belongs to and the workspaces they are in.
import Prosaic from 'prosaic-node';
const apiKey = process.env.PROSAIC_API_KEY;
if (!apiKey) throw new Error('Set PROSAIC_API_KEY first.');
const prosaic = new Prosaic(apiKey);
const { data: me } = await prosaic.me.retrieve();
console.log(
me.email,
me.workspaces.map((w) => `${w.name} (${w.id})`),
);curl https://app.prosaic.works/api/public/v1/me \
-H "Authorization: Bearer $PROSAIC_API_KEY"If the user belongs to more than one workspace, requests go to the one they last used in the app. Send x-workspace-id (or set workspaceId on the SDK client) to choose another.
3. List your entities
An entity is one set of books. Your new workspace already has its demo entities.
for await (const entity of prosaic.entities.list()) {
console.log(entity.id, entity.name, entity.currency);
}curl https://app.prosaic.works/api/public/v1/entities \
-H "Authorization: Bearer $PROSAIC_API_KEY"4. Pick a chart of accounts template
A new entity's accounts are copied from a template. Every workspace starts with a standard chart for its country (Standard NZ Business Template or Standard AU Business Template) plus Company, Trust, Sole Trader and Partnership charts.
const templates = await prosaic.charts.list().autoPagingToArray({ limit: 50 });
const standard = templates.find((t) => t.name.startsWith('Standard'));
if (!standard) throw new Error('No standard template in this workspace.');curl https://app.prosaic.works/api/public/v1/charts \
-H "Authorization: Bearer $PROSAIC_API_KEY"Note the id of the template you want.
5. Create an entity
name, type and accountTemplateId are required. type is one of individual, company, trust, partnership, rental or other.
const { data: entity } = await prosaic.entities.create({
name: 'Kowhai Cafe Ltd',
type: 'company',
accountTemplateId: standard.id,
});
console.log(entity.id);curl -X POST https://app.prosaic.works/api/public/v1/entities \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Kowhai Cafe Ltd",
"type": "company",
"accountTemplateId": "YOUR_TEMPLATE_ID"
}'The response wraps the entity in data. The entity takes its country, currency and financial year from the workspace. It is not GST registered unless you say so; Tax in NZ and AU covers the GST fields.
6. Find account codes and a tax rate
Journal lines name each account by its code, and each line with an amount needs a taxRateId.
Account codes come from the entity's chart of accounts:
const accounts = await prosaic.entityAccounts
.list(entity.id)
.autoPagingToArray({ limit: 500 });
for (const account of accounts) {
console.log(account.code, account.name, account.type);
}curl https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/charts \
-H "Authorization: Bearer $PROSAIC_API_KEY"In the standard templates, 4030 is Office Expense and 8220 is Accounts Payable. Templates can be edited, so check your own chart.
Tax rate IDs are on the entity itself, in taxRates[], both in the create response and in GET /entities?entityId=YOUR_ENTITY_ID. This journal carries no GST, so use the "No GST" rate: NZ_GST_0_NONE in New Zealand, AU_GST_0_NONE in Australia.
const noGst = entity.taxRates.find((rate) => rate.code === 'NZ_GST_0_NONE');
if (!noGst) throw new Error('No "No GST" rate on this entity.');curl "https://app.prosaic.works/api/public/v1/entities?entityId=YOUR_ENTITY_ID" \
-H "Authorization: Bearer $PROSAIC_API_KEY"7. Post a balanced journal
Debits must equal credits. Send amounts as decimal strings, and put each line's amount on one side only. Journals are posted straight away unless you send autoPost: false.
const journal = await prosaic.journals.create(entity.id, {
date: '2026-10-01',
narration: 'Office supplies, supplier invoice 1042',
taxMode: 'NO_TAX',
lines: [
{ entityAccountCode: '4030', taxRateId: noGst.id, debit: '115.00' },
{ entityAccountCode: '8220', taxRateId: noGst.id, credit: '115.00' },
],
});
console.log(journal.id, journal.status); // status is "posted"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": "Office supplies, supplier invoice 1042",
"taxMode": "NO_TAX",
"lines": [
{ "entityAccountCode": "4030", "taxRateId": "YOUR_NO_GST_RATE_ID", "debit": "115.00" },
{ "entityAccountCode": "8220", "taxRateId": "YOUR_NO_GST_RATE_ID", "credit": "115.00" }
]
}'Unlike most endpoints, journal creation returns the journal itself rather than a data envelope. Keep its logicalJournalId: voiding the journal or attaching files to it later takes that ID. Journals covers GST on lines, drafts, voids and attachments.
8. Read the trial balance
const trialBalance = await prosaic.reports.trialBalance(entity.id, {
asOfDate: '2026-10-31',
});
console.log(trialBalance.totals); // totalDebits, totalCredits, isBalanced, variancecurl "https://app.prosaic.works/api/public/v1/entities/YOUR_ENTITY_ID/trial-balance?asOfDate=2026-10-31" \
-H "Authorization: Bearer $PROSAIC_API_KEY"Reports return plain objects, not a data envelope. Amounts come back as decimal strings; use a decimal library such as Decimal.js for any arithmetic on them. accountGroups holds the per-account lines, signed as debits minus credits.
What next
- Embedded ledger — one entity per customer, and giving their accountant access.
- Journals — every field, GST handling, drafts and voids.
- Reports — P&L, balance sheet, general ledger and more.
- API reference — every endpoint, with its SDK method.
