# Quickstart

> From an API key to a posted journal and a trial balance, with the Node SDK or curl.

Source: https://developer.prosaic.works/docs/getting-started/quickstart

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](/docs/sdk/node) and with curl.

## Before you start

- **A Prosaic workspace.** Sign up at [app.prosaic.works/signup](https://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](mailto:developer@prosaic.works).
- **For the SDK:** Node.js 22 or later, and the SDK installed from its tarball as described in [Node SDK](/docs/sdk/node#install). 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.

1. Go to **Settings → Users**.
2. Find the user the key should act as (often yourself), open the **Actions** menu (⋯) and choose **Manage API keys**.
3. 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:

```bash
export PROSAIC_API_KEY="prsk_..."
```

A key acts as its user, with that user's access. [Authentication](/docs/getting-started/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.

```ts
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})`),
);
```

```bash
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.

```ts
for await (const entity of prosaic.entities.list()) {
  console.log(entity.id, entity.name, entity.currency);
}
```

```bash
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.

```ts
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.');
```

```bash
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`.

```ts
const { data: entity } = await prosaic.entities.create({
  name: 'Kowhai Cafe Ltd',
  type: 'company',
  accountTemplateId: standard.id,
});
console.log(entity.id);
```

```bash
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](/docs/ledger/tax-nz-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:

```ts
const accounts = await prosaic.entityAccounts
  .list(entity.id)
  .autoPagingToArray({ limit: 500 });

for (const account of accounts) {
  console.log(account.code, account.name, account.type);
}
```

```bash
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.

```ts
const noGst = entity.taxRates.find((rate) => rate.code === 'NZ_GST_0_NONE');
if (!noGst) throw new Error('No "No GST" rate on this entity.');
```

```bash
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`.

```ts
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"
```

```bash
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](/docs/ledger/journals) covers GST on lines, drafts, voids and attachments.

## 8. Read the trial balance

```ts
const trialBalance = await prosaic.reports.trialBalance(entity.id, {
  asOfDate: '2026-10-31',
});
console.log(trialBalance.totals); // totalDebits, totalCredits, isBalanced, variance
```

```bash
curl "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**](/docs/ledger/embedded-ledger) — one entity per customer, and giving their accountant access.
- [**Journals**](/docs/ledger/journals) — every field, GST handling, drafts and voids.
- [**Reports**](/docs/ledger/reports) — P&L, balance sheet, general ledger and more.
- [**API reference**](/docs/api) — every endpoint, with its SDK method.
