# Journals

> Manual journals: post or draft them, list them, attach files and void them.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List manual journals

`GET /api/public/v1/entities/{entityId}/journals`

SDK: `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

- `entityId` (string, required)

### Query parameters

- `page` (integer): Page number (starts at 1) Default: `1`.
- `pageSize` (integer): Number of items per page. Default: `20`.
- `dateFrom` (string, date): Start date for filtering journals (ISO 8601 format)
- `dateTo` (string, date): End date for filtering journals (ISO 8601 format)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `logicalJournalId` (string, nullable, required)
    - `postedAt` (string, date-time, nullable, required)
    - `postedBy` (string, nullable, required)
    - `poster` (object, nullable)
      - `id` (string, required)
      - `email` (string, required)
      - `name` (string, nullable, required)
      - `tradingName` (string, nullable, required)
      - `createdAt` (string, date-time, required)
    - `lines` (array of objects, required)
      - `id` (string, required)
      - `journalId` (string, required)
      - `parentId` (string, nullable, required)
      - `entityAccountId` (string, required)
      - `lineNumber` (number, required)
      - `type` (string, required)
      - `description` (string, nullable, required)
      - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
      - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
      - `taxRateId` (string, nullable, required)
      - `entityAccount` (object, required)
        - `id` (string, required)
        - `code` (string, required)
        - `name` (string, required)
      - `taxRate` (object, nullable, required)
        - `id` (string, required)
        - `code` (string, required)
        - `name` (string, required)
        - `description` (string, nullable, required)
        - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
    - `id` (string, required)
    - `narration` (string, required)
    - `date` (string, date-time, required)
    - `status` (string, required)
    - `type` (string, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `reconciliations` (array of objects)
      - `bankTransaction` (object, required)
        - `id` (string, required)
        - `description` (string, required)
        - `merchant` (object, nullable, required)
          - `id` (string, required)
          - `name` (string, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Bad request - missing or invalid parameters
  - `error` (string)
  - `code` (string)
  - `field` (string)
  - `value` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const page = await prosaic.journals.list(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a manual journal

`POST /api/public/v1/entities/{entityId}/journals`

SDK: `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 account `code` field (e.g., "2030") as the `entityAccountCode` in journal lines.
- **Tax rate IDs**: Retrieve the entity's tax rates via `GET /api/public/v1/entities` (filter by `entityId`). Use the `taxRates[].id` field as the `taxRateId` in 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

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `narration` (string, required)
- `date` (string, required)
- `lines` (array of objects, required)
  - `entityAccountCode` (string)
  - `entityAccountName` (string)
  - `taxRateName` (string)
  - `description` (string)
  - `credit` (string | number)
  - `debit` (string | number)
  - `taxRateId` (string)
  - `dimensionOptionIds` (array of strings)
- `editReason` (string)
- `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
- `fileIds` (array of strings)
- `autoPost` (boolean)

### Responses

- `200`: Successful response
  - `logicalJournalId` (string, nullable, required)
  - `postedAt` (string, date-time, nullable, required)
  - `postedBy` (string, nullable, required)
  - `poster` (object, nullable)
    - `id` (string, required)
    - `email` (string, required)
    - `name` (string, nullable, required)
    - `tradingName` (string, nullable, required)
    - `createdAt` (string, date-time, required)
  - `lines` (array of objects, required)
    - `id` (string, required)
    - `journalId` (string, required)
    - `parentId` (string, nullable, required)
    - `entityAccountId` (string, required)
    - `lineNumber` (number, required)
    - `type` (string, required)
    - `description` (string, nullable, required)
    - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
    - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
    - `taxRateId` (string, nullable, required)
    - `entityAccount` (object, required)
      - `id` (string, required)
      - `code` (string, required)
      - `name` (string, required)
    - `taxRate` (object, nullable, required)
      - `id` (string, required)
      - `code` (string, required)
      - `name` (string, required)
      - `description` (string, nullable, required)
      - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
  - `id` (string, required)
  - `narration` (string, required)
  - `date` (string, date-time, required)
  - `status` (string, required)
  - `type` (string, required)
  - `createdAt` (string, date-time, required)
  - `updatedAt` (string, date-time, required)
  - `reconciliations` (array of objects)
    - `bankTransaction` (object, required)
      - `id` (string, required)
      - `description` (string, required)
      - `merchant` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
- `400`: Bad request - validation failed, invalid account codes, an unbalanced journal, or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).
  - `error` (string)
  - `code` (string)
  - `details` (array of objects)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `404`: Not found - Entity not found
  - `error` (string)
- `500`: Internal server error
  - `error` (string)

### Example (Node SDK)

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

### Example (curl)

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

`POST /api/public/v1/entities/{entityId}/journals/bulk`

SDK: `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

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `autoPost` (boolean, required)
- `journals` (array of objects, required)
  - `date` (string, required)
  - `narration` (string, required)
  - `lines` (array of objects, required)
    - `entityAccountCode` (string)
    - `entityAccountName` (string)
    - `taxRateName` (string)
    - `description` (string)
    - `credit` (string | number)
    - `debit` (string | number)
    - `taxRateId` (string)
    - `dimensionOptionIds` (array of strings)
  - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
  - `fileIds` (array of strings)
- `idempotencyKey` (string)

### Responses

- `200`: Successful response
  - `replayed` (boolean, required)
  - `data` (array of objects, required)
    - `id` (string, required)
    - `logicalJournalId` (string, nullable, required)
    - `narration` (string, nullable, required)
    - `date` (string, date-time, required)
    - `status` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `201`: Successful response
  - `replayed` (boolean, required)
  - `data` (array of objects, required)
    - `id` (string, required)
    - `logicalJournalId` (string, nullable, required)
    - `narration` (string, nullable, required)
    - `date` (string, date-time, required)
    - `status` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: The request is malformed, or a taxed journal needs a GST account the entity lacks (SYSTEM_ACCOUNT_VALIDATION). Nothing was recorded.
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not found - Entity not found or access denied
- `409`: This idempotency key was already used for different journals (IDEMPOTENCY_KEY_REUSED)
- `422`: One or more journals can't be recorded (JOURNALS_REJECTED); `details.problems` lists each with its index. Nothing was recorded.
  - `error` (string)
  - `code` (string)
  - `details` (object)
    - `problems` (array of objects)
      - `index` (integer)
      - `message` (string)
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.journals.createBulk(entityId, {
  autoPost: true,
  journals: [
    {
      date: '2026-04-01',
      narration: 'Office supplies',
      lines: [
        {},
      ],
    },
  ],
});
```

### Example (curl)

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

`POST /api/public/v1/entities/{entityId}/journals/{journalId}/attachments`

SDK: `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

- `entityId` (string, required)
- `journalId` (string, required)

### Request body

Content type: `application/json`

- `fileIds` (array of strings, required)

### Responses

- `200`: Successful response
  - `success` (boolean, required): One of: `true`.
  - `attachments` (array of objects, required)
    - `id` (string, required)
    - `fileId` (string, required)
    - `createdAt` (string, date-time, required)
- `400`: Bad request - validation failed or files not found
  - `error` (string)
  - `details` (array of objects)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
- `404`: Not found - Journal not found
  - `error` (string)
- `500`: Internal server error
  - `error` (string)

### Example (Node SDK)

```ts
const result = await prosaic.journals.attachFiles(entityId, journalId, {
  fileIds: ['FILE_ID'],
});
```

### Example (curl)

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

`PATCH /api/public/v1/entities/{entityId}/journals/{journalId}/void`

SDK: `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

- `entityId` (string, required)
- `journalId` (string, required)

### Responses

- `200`: Successful response
  - `originalJournal` (object, required)
    - `id` (string, required)
    - `status` (string, required)
    - `voidedAt` (string, date-time, nullable, required)
    - `voidedBy` (string, nullable, required)
  - `reversalJournal` (object, required)
    - `id` (string, required)
    - `status` (string, required)
    - `postedAt` (string, date-time, required)
    - `postedBy` (string, required)
    - `voidedJournalId` (string, required)
  - `voidedAt` (string, date-time, required)
- `400`: Journal is not in a voidable state
- `404`: Journal not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const result = await prosaic.journals.void(entityId, journalId);
```

### Example (curl)

```bash
curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/void \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```