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:
- Send
updated_afterwith the last successfully stored checkpoint. - Process the returned journals in order.
- While
meta.has_moreistrue, request the next page using onlycursorandper_page. The cursor preserves a fixed snapshot. - After the final page, atomically store
meta.checkpoint. Use that value asupdated_afterin 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
}
}