All API resources
API reference

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

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

  • entityIdstringrequired

Query parameters

  • pageinteger

    Page number (starts at 1)

    Default: 1

  • pageSizeinteger

    Number of items per page

    Default: 20

  • dateFromstring (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 objectsrequired
    Show 13 child attributes
    • logicalJournalIdstringrequirednullable
    • postedAtstring (date-time)requirednullable
    • postedBystringrequirednullable
    • posterobjectnullable
      Show 5 child attributes
      • idstringrequired
      • emailstringrequired
      • namestringrequirednullable
      • tradingNamestringrequirednullable
      • createdAtstring (date-time)required
    • linesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • journalIdstringrequired
      • parentIdstringrequirednullable
      • entityAccountIdstringrequired
      • lineNumbernumberrequired
      • typestringrequired
      • descriptionstringrequirednullable
      • creditstringrequired

        Exact decimal serialized as a string. Use Decimal.js for arithmetic.

      • debitstringrequired

        Exact decimal serialized as a string. Use Decimal.js for arithmetic.

      • taxRateIdstringrequirednullable
      • entityAccountobjectrequired
        Show 3 child attributes
        • idstringrequired
        • codestringrequired
        • namestringrequired
      • taxRateobjectrequirednullable
        Show 5 child attributes
        • idstringrequired
        • codestringrequired
        • namestringrequired
        • descriptionstringrequirednullable
        • ratestringrequired

          Exact decimal serialized as a string. Use Decimal.js for arithmetic.

    • idstringrequired
    • narrationstringrequired
    • datestring (date-time)required
    • statusstringrequired
    • typestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • reconciliationsarray of objects
      Show 1 child attribute
      • bankTransactionobjectrequired
        Show 3 child attributes
        • idstringrequired
        • descriptionstringrequired
        • merchantobjectrequirednullable
          Show 2 child attributes
          • idstringrequired
          • namestringrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Bad request - missing or invalid parameters
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
Node SDK
const page = await prosaic.journals.list(entityId);
curl
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

  • entityIdstringrequired

Request body

application/json

  • narrationstringrequired
  • datestringrequired
  • linesarray of objectsrequired
    Show 8 child attributes
    • entityAccountCodestring
    • entityAccountNamestring
    • taxRateNamestring
    • descriptionstring
    • creditstring | number
    • debitstring | number
    • taxRateIdstring
    • dimensionOptionIdsarray of strings
  • editReasonstring
  • taxModestring

    One of: NO_TAX, TAX_INCLUSIVE, TAX_EXCLUSIVE

  • fileIdsarray of strings
  • autoPostboolean

Responses

200 Successful response

  • logicalJournalIdstringrequirednullable
  • postedAtstring (date-time)requirednullable
  • postedBystringrequirednullable
  • posterobjectnullable
    Show 5 child attributes
    • idstringrequired
    • emailstringrequired
    • namestringrequirednullable
    • tradingNamestringrequirednullable
    • createdAtstring (date-time)required
  • linesarray of objectsrequired
    Show 12 child attributes
    • idstringrequired
    • journalIdstringrequired
    • parentIdstringrequirednullable
    • entityAccountIdstringrequired
    • lineNumbernumberrequired
    • typestringrequired
    • descriptionstringrequirednullable
    • creditstringrequired

      Exact decimal serialized as a string. Use Decimal.js for arithmetic.

    • debitstringrequired

      Exact decimal serialized as a string. Use Decimal.js for arithmetic.

    • taxRateIdstringrequirednullable
    • entityAccountobjectrequired
      Show 3 child attributes
      • idstringrequired
      • codestringrequired
      • namestringrequired
    • taxRateobjectrequirednullable
      Show 5 child attributes
      • idstringrequired
      • codestringrequired
      • namestringrequired
      • descriptionstringrequirednullable
      • ratestringrequired

        Exact decimal serialized as a string. Use Decimal.js for arithmetic.

  • idstringrequired
  • narrationstringrequired
  • datestring (date-time)required
  • statusstringrequired
  • typestringrequired
  • createdAtstring (date-time)required
  • updatedAtstring (date-time)required
  • reconciliationsarray of objects
    Show 1 child attribute
    • bankTransactionobjectrequired
      Show 3 child attributes
      • idstringrequired
      • descriptionstringrequired
      • merchantobjectrequirednullable
        Show 2 child attributes
        • idstringrequired
        • namestringrequired
  • 400 Bad request - validation failed, invalid account codes, an unbalanced journal, or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
  • 404 Not found - Entity not found
  • 500 Internal server error
Node SDK
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
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

  • entityIdstringrequired

Request body

application/json

  • autoPostbooleanrequired
  • journalsarray of objectsrequired
    Show 5 child attributes
    • datestringrequired
    • narrationstringrequired
    • linesarray of objectsrequired
      Show 8 child attributes
      • entityAccountCodestring
      • entityAccountNamestring
      • taxRateNamestring
      • descriptionstring
      • creditstring | number
      • debitstring | number
      • taxRateIdstring
      • dimensionOptionIdsarray of strings
    • taxModestring

      One of: NO_TAX, TAX_INCLUSIVE, TAX_EXCLUSIVE

    • fileIdsarray of strings
  • idempotencyKeystring

Responses

200 Successful response

  • replayedbooleanrequired
  • dataarray of objectsrequired
    Show 5 child attributes
    • idstringrequired
    • logicalJournalIdstringrequirednullable
    • narrationstringrequirednullable
    • datestring (date-time)required
    • statusstringrequired
  • metaobject
    Show 1 child attribute
    • countnumberrequired

201 Successful response

  • replayedbooleanrequired
  • dataarray of objectsrequired
    Show 5 child attributes
    • idstringrequired
    • logicalJournalIdstringrequirednullable
    • narrationstringrequirednullable
    • datestring (date-time)required
    • statusstringrequired
  • metaobject
    Show 1 child attribute
    • countnumberrequired
  • 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.
  • 500 Internal server error
Node SDK
const { data } = await prosaic.journals.createBulk(entityId, {
  autoPost: true,
  journals: [
    {
      date: '2026-04-01',
      narration: 'Office supplies',
      lines: [
        {},
      ],
    },
  ],
});
curl
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

  • entityIdstringrequired
  • journalIdstringrequired

Request body

application/json

  • fileIdsarray of stringsrequired

Responses

200 Successful response

  • successbooleanrequired

    One of: true

  • attachmentsarray of objectsrequired
    Show 3 child attributes
    • idstringrequired
    • fileIdstringrequired
    • createdAtstring (date-time)required
  • 400 Bad request - validation failed or files not found
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
  • 404 Not found - Journal not found
  • 500 Internal server error
Node SDK
const result = await prosaic.journals.attachFiles(entityId, journalId, {
  fileIds: ['FILE_ID'],
});
curl
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

  • entityIdstringrequired
  • journalIdstringrequired

Responses

200 Successful response

  • originalJournalobjectrequired
    Show 4 child attributes
    • idstringrequired
    • statusstringrequired
    • voidedAtstring (date-time)requirednullable
    • voidedBystringrequirednullable
  • reversalJournalobjectrequired
    Show 5 child attributes
    • idstringrequired
    • statusstringrequired
    • postedAtstring (date-time)required
    • postedBystringrequired
    • voidedJournalIdstringrequired
  • voidedAtstring (date-time)required
  • 400 Journal is not in a voidable state
  • 404 Journal not found
  • 500 Internal server error
Node SDK
const result = await prosaic.journals.void(entityId, journalId);
curl
curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/void \
  -H "Authorization: Bearer $PROSAIC_API_KEY"