Java · Track 3 · Tutorial 1 of 6
Send a month's trial balance
Send the figures BrizoConsol's reports are built from: one month's movement on every account.
1What a month's trial balance is
A trial balance is the month's movement on every account: what was debited and credited to each during the month. It's the figure BrizoConsol's reports are built from - the other things you can send explain it, but only the trial balance moves the numbers.
2Write the month
Create Month.java. Each line is one account's debit and credit for September, both as positive figures:
Month.java
// Month.java - sends one month's trial balance.
import java.util.List;
import java.util.Map;
public class Month {
public static void main(String[] args) throws Exception {
String period = "2026-09";
String currency = "SGD"; // the company's own currency, as Companies showed it
String version = "v1"; // change it whenever this month's figures change
List<Map<String, Object>> movements = List.of(
Map.of("account_code", "1000", "debit", 20000.00, "credit", 0),
Map.of("account_code", "1200", "debit", 5000.00, "credit", 0),
Map.of("account_code", "2000", "debit", 0, "credit", 5000.00),
Map.of("account_code", "4000", "debit", 0, "credit", 30000.00),
Map.of("account_code", "5000", "debit", 8000.00, "credit", 0),
Map.of("account_code", "6000", "debit", 2000.00, "credit", 0));
var request = Brizo.written(Brizo.call("POST", "/organisations/" + Brizo.COMPANY_ID + "/trial-balances", Map.of(
"declarations", Map.of(
"source_reference", "my-ledger",
"period", period,
"value_basis", "company_base",
"rate_direction", "document_to_base",
"base_currency", currency),
"records", movements),
Map.of("Idempotency-Key", Brizo.COMPANY_ID + "-" + period + "-" + version)));
Brizo.show("Trial balance", request);
System.out.println("Recalculation: " + request.path("recalculation").asText());
}
}The declarations say what the figures are:
period- the month, asYYYY-MM.base_currency- the company's own currency. Any other is refused.value_basiscompany_base- the amounts are in that currency.rate_directionis required too; with amounts already in the company's currency it changes nothing.
The Idempotency-Key header is explained in the next tutorial: it makes sending the same month twice harmless.
3Send it
gradle -q run -Pmain=MonthCheck
Trial balance: request 92 - 6 created, 0 updated, 0 unchanged, 0 refused
Recalculation: pendingYour request number will be your own. Recalculation: pending means the figures are stored and waiting for tonight's run.
4A month is sent whole
Each send replaces everything this API holds for the company's month. Send every account that moved, every time - an account you leave out has no figure for that month afterwards.
5Know what else changes
- The group's reporting month becomes the month you sent. Send an earlier month later on, and the reporting month moves back to it.
- Reports update overnight. Read them straight away and you see the figures from before.
6If it's refused
These refuse the whole request, with 422 and the reason:
| base_currency_disagrees | The currency isn't the company's own. Use the one Companies.java showed. |
|---|---|
| period_locked | The month is locked in BrizoConsol. Someone has to unlock it first. |
| period_outside_window | The month is outside the range your plan allows actual figures for. The message names the range. |
| month_held_by_another_source | Another source - a spreadsheet upload or a connected accounting system - holds the month. See Take a month over from another source. |
Want more detail? See the documentation