Consolidation trigger
Asks for a group to be consolidated. The call records the request and answers at once; the consolidation itself runs in the overnight window. This is the "API-triggered consolidation, overnight only" capability, and it is the only way to ask for a consolidation without also sending data.
The endpoints
| Method | Path | What it does |
|---|---|---|
| POST | /api/v1/organisations/{organisation}/consolidation-requests Try it |
Records a request for the group to be consolidated overnight |
| GET | /api/v1/organisations/{organisation}/consolidation-requests/{id} Try it |
What became of that request |
Both need a bearer token, a credential issued for the group, and the consolidation.trigger
scope. The trigger is part of the Premium edition; on any other edition the call answers 403
with The API is available on the Premium edition.
What a trigger does, and what it does not
- It records intent, and who asked. The answer is
202 Acceptedwith the request's own resource in the body and its URL inLocation. No figure is returned, and no figure changes during the call. The request is written to the System Audit Trail asconsolidation.requested, naming the credential (or the AI connection) that asked for it. - It writes no data. A month of ledger is sent through trial balance, invoices, bills, journal lines or operational data. This endpoint only asks for the consolidation of whatever the group already holds.
- It runs overnight. The nightly run dispatches the recalculation for every request
waiting; the run is at
01:40in the installation's timezone (Asia/Singapore in the hosted service, so the evening of the same day in Europe and the Americas). Nothing is consolidated in the seconds after the call. - It is safe to repeat. A group can only be waiting for one night's consolidation, so a
second trigger while the first is still
pendinganswers with that same request and creates nothing.meta.deduplicatedsays which answer you received.
One request per group
A trigger answers with the request already waiting, if there is one. That makes a retry after a timeout, or a scheduler that fires twice, harmless: the group is consolidated once, and the request you get back is the one that will run.
| Answer | Meaning |
|---|---|
meta.deduplicated: false | This call created the request that will run tonight. |
meta.deduplicated: true | A request was already waiting; its id is the
one in data, and nothing new was created. |
Once the night run has taken a request (dispatched) or it has failed, the next trigger creates a
new one: a new day's intent is a new request, not yesterday's.
The request's states
| Status | What it means | What to do |
|---|---|---|
pending | Recorded; tonight's run has not taken it yet. | Nothing. Poll, or read the group's figures after the run. |
dispatched | The night run has handed the consolidation to the workers. | Read the figures; dispatched_at says when the run picked it up. |
failed | The run could not dispatch it. failure says why. |
Fix the cause and trigger again; a failed request is not retried by the run. |
dispatched is not "finished": the recalculation runs on the workers after dispatch, and a group
whose recalculation is still running answers unchanged figures until it completes. The read endpoints say
what the figures are now; the request says that the work was started.
A trigger, end to end
POST /api/v1/organisations/149/consolidation-requests
Authorization: Bearer {access_token}
202 Accepted
Location: /api/v1/organisations/149/consolidation-requests/12
{
"data": {
"id": 12,
"organisation_id": 149,
"status": "pending",
"requested_at": "2026-10-28T14:02:11+08:00",
"dispatched_at": null,
"failure": null
},
"links": { "self": "…/organisations/149/consolidation-requests/12" },
"meta": { "deduplicated": false }
}
A second trigger the same afternoon answers the same request:
202 Accepted
{
"data": { "id": 12, "status": "pending", "…": "…" },
"links": { "self": "…/organisations/149/consolidation-requests/12" },
"meta": { "deduplicated": true }
}
The next morning, the same URL answers what the run did:
GET /api/v1/organisations/149/consolidation-requests/12
{
"data": {
"id": 12,
"organisation_id": 149,
"status": "dispatched",
"requested_at": "2026-10-28T14:02:11+08:00",
"dispatched_at": "2026-10-29T01:40:03+08:00",
"failure": null
},
"links": { "self": "…/organisations/149/consolidation-requests/12" }
}
How it relates to a trial-balance write
A month sent through trial balance also waits for the same overnight run.
Its write answers recalculation: "pending", and the night run dispatches the recalculation —
so pushing a month and then reading the statements immediately would read the figures as they were before
the push. A caller that needs the new figures on a chosen morning can either trigger explicitly after the
last write, or read the request's recalculation until it reads done.
What it refuses
| Answer | When |
|---|---|
403 The API is available on the Premium edition. | The group is not on the edition that carries the API. |
403 This credential does not hold the consolidation.trigger scope. |
The credential was issued without the trigger scope. |
404 No such organisation. | The company is not one this credential was issued for. The API never confirms another group's company exists. |
404 No such consolidation request. | The request id belongs to another group. |