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.

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.

Timestamps are ISO-8601 with an offset, as everywhere else in the API. Every filter above is an equality or a range, so supply whole values rather than fragments. To narrow by action, request the period you need and filter the results on your side. The Action By box on the Audit Trail screen maps to created_by_name, which is why it needs the actor’s profile name exactly as stored, not a login or an e-mail address.

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 five checks are the same for both methods.

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 the same screen 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.