finov.ioDocumentationHome

List posted journals

API Documentation / Resources / Journals

List posted journals

GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/journals

Required OAuth scope: accounting:read

Lists immutable posted journals from every supported source workflow.

Filter Meaning
source Stable source family such as invoice or manual_journal.
source_id UUID of the originating business record.
contact_id Journals associated with one contact.
from_date, to_date Inclusive posting-date range.
journal_number Exact assigned journal number.
updated_after Start an incremental sync after an RFC 3339 checkpoint.

Reliable incremental sync

To retrieve every new or updated journal without unstable page offsets:

  1. Send updated_after with the last successfully stored checkpoint.
  2. Process the returned journals in order.
  3. While meta.has_more is true, request the next page using only cursor and per_page. The cursor preserves a fixed snapshot.
  4. After the final page, atomically store meta.checkpoint. Use that value as updated_after in the next sync cycle.

The sync feed is ordered by updated_at ascending and then by a stable internal tie-breaker. Cursors are opaque and scoped to the subsidiary; clients must not inspect or construct them. A journal updated while a snapshot is being read is returned during the next sync cycle. Removed journals remain in the feed as records with deleted: true, allowing a client to remove or mark its local copy.

Requests without updated_after or cursor use ordinary page-number browsing ordered by posting date descending. Page-number pagination is not suitable for synchronization. Journals cannot be created directly through this resource.

Parameters

Name In Required Type Description
tenant_id path Yes string (uuid) UUID of the authorized company group.
subsidiary_id path Yes string (uuid) UUID of the subsidiary containing the ledger.
source query No string
source_id query No string (uuid)
contact_id query No string (uuid)
from_date query No string (date)
to_date query No string (date)
journal_number query No string
updated_after query No string (date-time) RFC 3339 checkpoint from the previous completed sync. Starts a new fixed-snapshot sync cycle.
cursor query No string Opaque next_cursor from the preceding sync page. Do not combine with browsing parameters.
page query No integer Positive page number.
per_page query No integer Records per page.

Request

GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/journals HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}

Responses

Status Description
200 A page of posted journals.
401 Access token is missing, expired, revoked, or invalid.
403 Token lacks the required scope or granted accounting context.
422 Journal filters failed validation.

200 example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "553aa91a-e8c2-4c6f-b800-07a2b92efdb1",
      "journal_number": "JRN-2026-0082",
      "date": "2026-08-10",
      "source": "invoice",
      "source_id": "f54ca5ce-c915-417b-9514-818ba58a21cb",
      "contact_id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
      "currency_code": "NZD",
      "exchange_rate": "1.00000000",
      "gross": "1725.0000",
      "narration": "Sales invoice INV-2026-0042",
      "lines": [
        {
          "id": "9dbf18ab-f3d5-4ee7-a985-091960377b7b",
          "account_id": "f159c40d-d09c-44a8-85f1-6ba96ca583ee",
          "account_code": "1100",
          "description": "Accounts receivable",
          "amount": "1725.0000",
          "tax_rate_id": null,
          "dimension_element_ids": []
        },
        {
          "id": "55d27ea8-8f48-4822-8be4-87dcc536aadc",
          "account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
          "account_code": "4100",
          "description": "Advisory services",
          "amount": "-1500.0000",
          "tax_rate_id": "d98226c2-ad80-4345-b117-5630de766842",
          "dimension_element_ids": []
        }
      ],
      "history": [],
      "posted_at": "2026-08-10T13:30:00Z",
      "updated_at": "2026-08-10T13:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "last_page": 1,
    "total": 1
  }
}