Build a connector
A connector pushes another system's accounting data into BrizoConsol and reads the group's figures back. This page is the order the work has to happen in, what to check at each step, and the things that go wrong when it does not.
GET /api/v1/schemas/{kind}. Read it rather than guessing — it states the declarations,
the records, which fields make two records the same record, the record limit and every error code the kind
can answer.Step 1 — Decide what you are sending
Six kinds are written, and only one of them moves a report figure:
| Kind | What it carries | Moves a figure? |
|---|---|---|
| accounts | The chart of accounts | No |
| trial_balance | A month's movement per account | Yes — this is the ledger |
| invoices | Sales documents with their lines | No |
| bills | Purchase documents with their lines | No |
| transactions | Journal lines | No |
| operation_data | The dashboard datasets | No |
The detail kinds explain the figures the trial balance produces. A month is complete with the trial balance alone; the documents make a figure answerable to a row.
Step 2 — Create the credential and choose the scopes
In BrizoConsol: Settings → Global Settings → Integrations → API Access. The credential belongs to the group, names the organisations it may use, and its secret is shown once. Give it the smallest set of scopes the connector needs — see Create a credential.
accounts.write,trial_balance.write— a ledger connector.invoices.write,bills.write,transactions.write,operation_data.write— the detail, one scope each.*.readscopes — only if the connector also reads figures back.consolidation.trigger— only if it triggers an overnight consolidation.
Step 3 — Get a token
POST /api/v1/tokens
Content-Type: application/json
{ "client_id": "...", "client_secret": "..." }
An access token lives 60 minutes; a refresh token lives 30 days and is spent when used. Refresh before the
hour is up, and treat a 401 as "refresh, then retry once" rather than as a failure of the
data. The full exchange is on Tokens.
Step 4 — Load the chart of accounts first
A trial balance never creates an account: a code the company does not hold is refused with
account_not_found. Send accounts before the first
month, and again whenever the chart changes.
POST /api/v1/organisations/149/accounts
{ "declarations": { "source_reference": "netsuite-chart", "mode": "merge" },
"records": [ { "code": "4000", "name": "Sales revenue", "type": "Revenue" } ] }
Concern: the code is the identity. Renaming a code is a new account and a vanished one, so keep codes stable and change the name instead.
Step 5 — Send a month whole
POST /api/v1/organisations/149/trial-balances
Idempotency-Key: 149-2026-09-netsuite-v3
{
"declarations": {
"source_reference": "netsuite-monthly",
"period": "2026-09",
"value_basis": "company_base",
"rate_direction": "document_to_base",
"base_currency": "SGD",
"mode": "replace_period"
},
"records": [
{ "account_code": "4000", "debit": 0, "credit": 12500.00 },
{ "account_code": "1100", "debit": 12500.00, "credit": 0 }
]
}
- A month is sent whole. Under
replace_period, a code absent from the payload has no rows in that month afterwards. There is no partial trial balance and no line to delete individually. - The currency has to match the company.
base_currencyis the company's reporting currency; a different one is refused withbase_currency_disagrees. - Amounts are in that currency (
value_basis: company_base), andrate_directionsays which way any rate a record states runs. - One month has one owner. If another source holds the month, the request is refused
with
month_held_by_another_sourceunless it states"switch_source": true, which removes the other source's rows for that month and reportsresult.switched_fromandresult.rows_removed. Do not switch silently: the other source is usually the company's accounting system.
Step 6 — Wait for the overnight consolidation
The write answers 202 with recalculation: "pending". The reports are rebuilt by
the overnight run, so a read in the next few seconds answers the figures as they were before the push.
Two ways to know when it is done:
- Poll
GET …/requests/{id}untilrecalculationreadsdone, orfailedwith the step that failed. - Trigger
POST …/consolidation-requestsafter the last write of the day; the request'sstatusmoves frompendingtodispatchedat01:40installation time. A second trigger while one is waiting answers the same request, so a retry is harmless — see Consolidation trigger.
Concern: a webhook_url is called when the write finishes, not when
the consolidation does. Its body states recalculation: "pending"; do not read that as
"the figures are ready".
Step 7 — Add the detail, if you have it
Invoices, bills, journal lines and operational data take the same shape: declarations about the month, then records. They are stored per source, explain the figures, and never move them.
Concern: a journal line that a document already explains is reported as
suppressed rather than stored twice — the same amount reaching BrizoConsol as both a document
and a ledger line would otherwise double-count.
Step 8 — Schedule it
A working order for a monthly cycle, per company:
- Refresh the token.
- Send the chart, if it changed.
- Send the month's trial balance (
replace_period, oneIdempotency-Keyper company, month and feed version). - Send the documents and journal lines for that month.
- Trigger the consolidation once, and record the request id.
- Next morning, read
recalculationfor the writes andstatusfor the trigger; only then publish.
The concerns, in one place
| Concern | What to do |
|---|---|
| Consolidation is not instant | Write, trigger, read the next morning. Do not read statements immediately after a push and expect the new month. |
| Retries duplicate work | Send an Idempotency-Key; a repeated
request answers with the first and writes nothing. Consolidation triggers deduplicate on their
own. |
| A month has one owner | Decide who owns a month before going live. Use
switch_source only to hand it over deliberately. |
| Closed periods | A locked month answers period_locked; a month
outside the edition's actual-history window answers period_outside_window. Both are
permanent for that month until someone unlocks or the plan changes. |
| Limits | 1,000 records per request (the group's own figure is in the
schema), 4 MB body, 60 requests a minute for the group - not for each token - and one write at a time
per company. A second write arriving during one gets 429 and writes nothing, so send it
again rather than in parallel. Split a large month by account and send it in one
replace_period sequence. The per-company caps - 300 accounts, 1,000 documents a month,
100 lines a document - are on Caps per company. |
| Scopes are the whole of a credential's power | One credential per system, write scopes only where writing happens, and revoke rather than reuse when a system is retired. |
| Another group's company is not yours | It answers 404, not
403. Treat 404 on a company you expect as a configuration error in the
credential, not as a transient failure. |
| Addressing the group | Reads of group figures answer for the group whichever company the path names. Writes need the company that owns the data. |
| Errors are per record | A payload is not all-or-nothing: accepted records are
stored and refused ones are listed with an index, an identity and a code. Check
counts.rejected and …/results, or a partly-loaded month goes
unnoticed. |
Go-live checklist
- The schema for every kind you send has been read, not guessed.
- The chart is loaded, and every code in your month exists.
base_currencymatches each company, and the amounts are in it.- An
Idempotency-Keyis sent on every write, and is stable across retries. - Nothing reads statements before
recalculationisdone. - A consolidation trigger is sent after the last write, and its status is checked the next morning.
counts.rejectedis zero for a full month, or the refusals have been read.- The credential holds only the scopes the connector uses.