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

MethodPathWhat 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

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.

AnswerMeaning
meta.deduplicated: falseThis call created the request that will run tonight.
meta.deduplicated: trueA 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

StatusWhat it meansWhat to do
pendingRecorded; tonight's run has not taken it yet. Nothing. Poll, or read the group's figures after the run.
dispatchedThe night run has handed the consolidation to the workers. Read the figures; dispatched_at says when the run picked it up.
failedThe 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

AnswerWhen
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.