Audit Trail API

The audit trail records what changed somewhere else in BigLedger: which record, what it looked like before and after, who did it, and when. It is the data behind the Audit Trail screen in the Tenant Admin Applet, and behind the Audit Trail item in every applet’s own sidebar.

The same record is served by two independent surfaces. Which one you want depends on whose data you are reading.

Base paths:

See API Reference for authentication, and the Data API reference for the response envelope, streaming and paging.

Permissions

The caller needs one of these for each operation. The two surfaces have separate families with the same shape.

A platform administrator passes every check on the platform surface without holding any of its codes. A failed check answers CLIENT_AUTH_USER_NOT_AUTHORIZED, which is an authorisation problem rather than an authentication one.

Endpoints

Reads behave slightly differently on the two surfaces, which is worth knowing if you are building a listing.

• Tenant. Permission is checked once per request. A caller who passes the check sees every field of every record returned.
• Platform. Records outside the caller’s permission are returned with "status": "PERMISSION_DENIED" and their remaining fields empty, rather than being omitted. This is a response-only marker, so do not send it back on a write.

The AppletAuditTrailContainer

The same shape on both surfaces, and the same shape a read returns.

{
  "bl_applet_audit_trail": {
    "guid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "applet_guid": "6f1c9e10-3a44-4f2e-9a71-0c3d6b2f77aa",
    "applet_code": "internalSalesInvoiceApplet",
    "action": "UPDATED",
    "foreign_table": "bl_fi_generic_doc_hdr",
    "foreign_key": "9c2a5f31-77b2-4d0a-8f4e-2b6a1d5c8e33",
    "date_txn": "2026-09-15T10:04:22+08:00",
    "message_json": { "payload": { } },
    "status": "ACTIVE",
    "revision": "0f3e7a52-1c6b-4a9d-8e21-7b4c9f0a1d26"
  }
}

PUT takes the whole record back, not a patch. A field you leave out is written as null.

bl_applet_audit_trail

What writes rows

Most rows are not written by an API caller. BigLedger writes them itself when an audited operation runs, and those rows have a predictable shape.

• action and descr both carry the operation, one of CREATED, UPDATED, DELETED, DISCARD
• foreign_table and foreign_key identify the audited record
• applet_guid and applet_code come from the caller’s token, and are set only when that token carries an applet
• message_json is {"payload": { … }}, and the payload holds whichever of old_data, new_data and delete_data applied, plus an auth_token_fields object describing the caller

So a CREATED row carries new_data alone, an UPDATED row carries old_data and new_data so the two can be compared field by field, and a DELETED row carries delete_data, the removed record kept after the record itself is gone.

Querying

Both /query endpoints take the same parameters. The shared paging parameters first: limit (default 100), offset (default 0), orderBy (default the record’s guid), order (ASC or DESC) and calcTotalRecords, which must be true for totalRecords in the envelope to be anything but 0.

Every filter is an equality or a range. There is no partial match and no wildcard anywhere on this endpoint, so supply whole values rather than fragments. These eleven match exactly and need no further explanation: applet_guid, applet_code, foreign_table, foreign_key, link_guid, txn_type, event_code, obj_type, id_user, id_device, id_user_agent, created_by_subject_guid and updated_by_subject_guid.

The rest behave in ways their names do not tell you.

Timestamps are ISO-8601 with an offset, as everywhere else in the API.

Errors on write

POST and PUT validate before anything is stored, on both surfaces, and a failure returns HTTP 400 with the failing checks in the envelope. The same five checks run for both methods, and the fifth, on the two actor fields, can return any of four codes, so there are eight in all.

DELETE returns CLIENT_VALIDATION_GUIDDOESNOTEXIST with HTTP 404 when no record carries that guid. The full list of code values is on the Error Codes page.

Scope

• Credentials. These endpoints are served for signed-in users. The server-to-server surface an access key reaches is described in the integration path and the Data API reference.
• Write access. POST, PUT and DELETE are available to callers holding the matching permission in the table above. Grant those permissions deliberately, and keep read-only integrations on the READ permission alone.
• Coverage. Records are written for the operations that support auditing. If a search returns nothing, widen the date range and re-check applet_code and foreign_table before drawing a conclusion.
• Other audit trails. Claims, entities, journal lines, cashbook transaction lines, memberships and several other records keep their own audit trails. This page covers the applet audit trail only.

Related

• Tenant Admin Applet covers the Audit Trail screen this API serves: its listing columns, advanced search and detail view.
• Audit Trail guide walks both screens through as an investigation, for a reader who is not calling the API.
• API Reference lists the API families, and which of them have a page.
• Authentication covers what may go in the Authorization header, and where each credential works.
• Error Codes lists every code value the API can return.