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.

Before you start. The layout of every payload is published without a token: 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:

KindWhat it carriesMoves a figure?
accountsThe chart of accountsNo
trial_balanceA month's movement per accountYes — this is the ledger
invoicesSales documents with their linesNo
billsPurchase documents with their linesNo
transactionsJournal linesNo
operation_dataThe dashboard datasetsNo

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.

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 }
  ]
}

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:

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:

  1. Refresh the token.
  2. Send the chart, if it changed.
  3. Send the month's trial balance (replace_period, one Idempotency-Key per company, month and feed version).
  4. Send the documents and journal lines for that month.
  5. Trigger the consolidation once, and record the request id.
  6. Next morning, read recalculation for the writes and status for the trigger; only then publish.

The concerns, in one place

ConcernWhat to do
Consolidation is not instantWrite, trigger, read the next morning. Do not read statements immediately after a push and expect the new month.
Retries duplicate workSend an Idempotency-Key; a repeated request answers with the first and writes nothing. Consolidation triggers deduplicate on their own.
A month has one ownerDecide who owns a month before going live. Use switch_source only to hand it over deliberately.
Closed periodsA 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.
Limits1,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 powerOne 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 yoursIt 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 groupReads of group figures answer for the group whichever company the path names. Writes need the company that owns the data.
Errors are per recordA 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