Sintropix Audit Trail API: Query Forensic Change History

The audit trail is a forensic, append-only log of every mutating request against an Organization’s data. Each row stores the actor, credential type, declared actor, request id, route, method, and a diff of what changed. GET requests do not produce audit records. The trail belongs to the Organization. You read it in two ways:

The Log of the Organization, every write to any of its Entities and to the data the Organization shares, filtered by Entity if you like: GET /api/organizations/:organizationId/audit-trail.
The Actividad of one record, its own history: GET /api/entities/:entityId/audit-trail.

Both routes need books read in the Organization. Both return the same page shape.

Open in the app. This resource has a page in the Sintropix web app at https://app.sintropix.com/organizations/{organizationId}/settings/log, where each id in braces is the same UUID as in the API route or response. The Log lives in the Organization's settings, with an Entidad filter. A record's own history is in the Actividad tab of its panel. When you mention a record to a user, include that link. See Link to the App for the full URL grammar.

The Log moved from the Entity to the Organization. GET /api/entities/:entityId/audit-trail now requires tableName and rowId. To list every write of an Entity, call the Organization route with entityIds.

List the Organization Log

GET /api/organizations/:organizationId/audit-trail Returns a paginated page of the Organization’s audit envelopes, plus the named resources needed to render them without extra lookups. Writes that belong to no Organization never appear. With no filter, the page lists every envelope of the Organization. That includes the envelopes of Organization routes that name no Entity, such as a Partner merge or a Dimension change. Those have entityId set to null, and the app labels them Empresa. Query params

Param	Type	Required	Description
`entityIds`	UUID	No	Keep the envelopes of this Entity. Repeat the param for several Entities, up to 100.
`includeOrganizationEnvelopes`	boolean	No	`true` keeps the envelopes that name no Entity (Empresa). Defaults to `false`.
`cursor`	integer	No	Page cursor (positive integer). Pass the `nextCursor` from the previous page to fetch the next one.
`limit`	integer	No	Page size, 1 to 100. Defaults to 50.
`from`	ISO date	No	Filter envelopes on or after this date. Must be before or equal to `to` when both are given.
`to`	ISO date	No	Filter envelopes on or before this date.
`actorUserId`	UUID	No	Filter to a specific user.

How the Entity filter matches Send entityIds, includeOrganizationEnvelopes, or both, to narrow the Log:

An envelope matches an Entity when it names that Entity, or when it changes a row of that Entity. For example, a Partner merge names no Entity, but it shows under each Entity whose rows it changed.
Inside a matched envelope, the changes to rows of Entities you didn’t select are hidden. Changes to rows the whole Organization shares, such as a Partner, always show.
A row that moved between two Entities shows under both.
With includeOrganizationEnvelopes=true, the envelopes that name no Entity also match.

Selecting every Entity plus Empresa gives the same Log as no filter. An API key confined to one Entity reads its own Entity and the Empresa envelopes by default. Asking for another Entity in entityIds answers 404 with ENTITY_NOT_FOUND_ERROR.

curl -s "https://api.sintropix.com/api/organizations/$ORGANIZATION_ID/audit-trail?entityIds=$ENTITY_ID&includeOrganizationEnvelopes=true&limit=50" \
  -H "x-api-key: $SINTROPIX_API_KEY"

List the history of one record

GET /api/entities/:entityId/audit-trail Returns the audit envelopes that changed one row of the Entity, the same history the Actividad tab of a record shows in the app. An envelope never shows a change to another Entity’s rows. Query params

Param	Type	Required	Description
`tableName`	string	Yes	The table of the row. See accepted values below.
`rowId`	UUID	Yes	The id of the row.
`cursor`	integer	No	Page cursor (positive integer). Pass the `nextCursor` from the previous page to fetch the next one.
`limit`	integer	No	Page size, 1 to 100. Defaults to 50.
`from`	ISO date	No	Filter envelopes on or after this date. Must be before or equal to `to` when both are given.
`to`	ISO date	No	Filter envelopes on or before this date.
`actorUserId`	UUID	No	Filter to a specific user.

Accepted tableName values The trail records changes to the tables of the books and the records around them, for example ledger_entry, ledger_entry_line, invoice, invoice_attachment, attachment, partner, partner_alias, partner_bank_details, entity_partner, bank_movement, bank_movement_attachment, bank_account, reconciliation_allocation, fixed_asset, fixed_asset_class, fixed_asset_depreciation_entry, intercompany_entry, expense_claim, and task. Any string is accepted; one that names no audited row matches nothing. Some parents also pull in their child rows: tableName=ledger_entry returns changes to that entry and to its ledger_entry_line rows; tableName=invoice returns changes to that invoice and to its invoice_attachment links; tableName=bank_movement returns changes to that movement and to its bank_movement_attachment links; tableName=partner returns changes to that Partner, its partner_alias rows, its entity_partner links, and the Partners merged into it. The invoice and bank movement histories also carry the attachment rows of the files linked in the same request. For tableName=partner_bank_details, pass the Partner’s id as rowId. For an Expense Rendition, tableName=invoice also returns the history of the Expense Claim it came from: who submitted it and who approved it.

curl -s "https://api.sintropix.com/api/entities/$ENTITY_ID/audit-trail?tableName=invoice&rowId=$INVOICE_ID" \
  -H "x-api-key: $SINTROPIX_API_KEY"

Response

Both routes answer 200 with this page:

Field	Type	Description
`envelopes`	array	One envelope per mutating request, newest first. See below.
`namedResources`	object	Display facts for the resources the envelopes on this page reference. See below.
`nextCursor`	integer or `null`	Cursor for the next page, or `null` on the last page.

Each envelope:

Field	Type	Description
`id`	integer	Envelope id.
`occurredAt`	ISO datetime	When the request was processed.
`requestId`	string	Server-generated unique id for the request.
`actorUserId`	UUID or `null`	The authenticated user, when there was one.
`actor`	object or `null`	`{ id, name, role, deleted }` of the authenticated user, as they were at the write. `role` is the user’s Membership Role in the Organization of the write (`staff`, `client`, or `viewer`), or `null` when they held no Membership there. `deleted` is `true` when a Superadmin has deleted the user since.
`credentialType`	enum	`session`, `api_key`, `oauth`, or `system`. `oauth` marks a write made by a connected app with an OAuth access token.
`apiKeyId`	UUID or `null`	The API key used, for `api_key` requests.
`connectedAppClientId`	string or `null`	The OAuth `client_id` of the connected app, for `oauth` requests.
`connectedAppName`	string or `null`	The name the connected app declared for itself, as it read at the time of the write, for `oauth` requests.
`declaredActor`	string or `null`	Value of the `x-audit-actor` header on API-key mutations.
`declaredReason`	string or `null`	Value of the `x-audit-reason` header (trimmed) explaining why the change was made. Required on API-key and OAuth-token mutations; optional on browser sessions. `null` on rows written before the header existed.
`declaredTrigger`	`slack` \| `app` \| `chat` \| `schedule` \| `terminal` \| `null`	Value of the `x-audit-trigger` header: what started the agent turn behind the write. `schedule` means a schedule started it. The other values name where a person’s message started it. `null` when the request sent no trigger, on changes made by Sintropix itself, and on rows written before the header existed.
`route`	string	The endpoint pattern that produced the mutation. For a change made by a scheduled job, the job’s name. See Scheduled jobs.
`method`	string	HTTP method, for example `POST`. `CRON` for a change made by a scheduled job.
`params`	object	Path parameters of the request.
`organizationId`	UUID or `null`	The Organization of the write.
`entityId`	UUID or `null`	The entity scope of the change.
`ipAddress`	string or `null`	IP address of the client that sent the request, not of a proxy in between. An IPv6 address is written in full, with each group padded to four digits, for example `2800:0150:011e:1a00:1c8f:6d2a:3b4e:9f01`.
`userAgent`	string or `null`	Caller user agent.
`changes`	array	One change per affected row. See below.

Each change:

Field	Type	Description
`id`	integer	Change id.
`envelopeId`	integer	The envelope this change belongs to.
`occurredAt`	ISO datetime	When the row changed.
`tableName`	string	One of the table names listed above.
`rowPrimaryKey`	object	Primary key of the affected row, for example `{ "id": "..." }`.
`operation`	enum	`insert`, `update`, or `delete`.
`before`	object or `null`	Row image before the change. `null` on insert.
`after`	object or `null`	Row image after the change. `null` on delete.

Keys inside before, after, and rowPrimaryKey are the stored column names in snake_case (for example entry_date, partner_id), not the camelCase names used elsewhere in the API. namedResources carries the display facts of exactly the resources the page’s envelopes point at, so a feed can render names without further lookups:

Field	Type	Description
`ledgerAccounts`	array	`{ id, code, name }`
`partners`	array	`{ id, name }`
`bankAccounts`	array	`{ id, name, currency }` where `currency` is an ISO 4217 code.
`sources`	array	`{ id, name }`
`ledgerEntryLines`	array	`{ id, accountName, entryMemo, entryDate }` where `entryMemo` may be `null` and `entryDate` is `YYYY-MM-DD`.

A resource that no longer exists is absent from these lists; treat an id you cannot resolve as unknown.

{
  "envelopes": [
    {
      "id": 1842,
      "occurredAt": "2025-01-15T09:23:00.000Z",
      "requestId": "req_8f1c2e7a9b",
      "actorUserId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
      "actor": { "id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b", "name": "Ana Perez", "role": "client", "deleted": false },
      "credentialType": "api_key",
      "apiKeyId": "7a1e4d2c-3b5f-4e6a-8c9d-0f1a2b3c4d5e",
      "connectedAppClientId": null,
      "connectedAppName": null,
      "declaredActor": "my-agent",
      "declaredReason": "Rename Acme Ltd to its legal name after the vendor update email",
      "declaredTrigger": null,
      "route": "/entities/:entityId/partners/:partnerId",
      "method": "PATCH",
      "params": { "entityId": "3f2c9a1e-7b4d-4c8e-9f0a-2b6d8e1c4a57", "partnerId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e" },
      "organizationId": "7c1e4b2a-3d5f-4a6b-8c9d-0e1f2a3b4c5d",
      "entityId": "3f2c9a1e-7b4d-4c8e-9f0a-2b6d8e1c4a57",
      "ipAddress": "203.0.113.10",
      "userAgent": "curl/8.4.0",
      "changes": [
        {
          "id": 5120,
          "envelopeId": 1842,
          "occurredAt": "2025-01-15T09:23:00.000Z",
          "tableName": "partner",
          "rowPrimaryKey": { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e" },
          "operation": "update",
          "before": { "name": "Acme Ltd" },
          "after": { "name": "Acme Limited" }
        }
      ]
    }
  ],
  "namedResources": {
    "ledgerAccounts": [],
    "partners": [{ "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "name": "Acme Limited" }],
    "bankAccounts": [],
    "sources": [],
    "ledgerEntryLines": []
  },
  "nextCursor": 1841
}

What the trail captures

The audit trail is row-level and automatic: every write is recorded by the database itself, so no endpoint can skip it. Every mutating request produces one Audit Envelope grouping its Audit Changes:

Actor: actorUserId plus the name and role the authenticated user had at the write. A deleted user keeps that name and role in the trail, and the Log shows (eliminado) after their name.
Credential type: session for browser sessions, api_key for API key requests, system for changes made by Sintropix itself
Declared actor: the value of the x-audit-actor header on API-key mutations (stored as a claim, not a verified identity). Changes Erwin makes while a person chats with him in the app carry erwin, with that person as the actor. A Source Feed sync that writes the Standing or Tax Period of a landed DTE carries source-feed, credited to the system.
Declared reason: the value of the x-audit-reason header (trimmed, up to 500 characters) explaining why the change was made; required on API-key mutations, optional on browser sessions
Declared trigger: the value of the optional x-audit-trigger header (stored as a claim), naming what started the agent turn behind the write. Every write Erwin makes carries the trigger of his turn: schedule when a schedule started it, or slack, app, chat, or terminal when a person’s message there started it. An envelope whose declaredActor starts with erwin and whose declaredTrigger is schedule is a change Erwin made on his own
Request id: a server-generated unique id grouping all changes in one request
Route and HTTP method: the endpoint that produced the mutation, or the scheduled job that made it
Entity id: the entity scope the change occurred within
Diff: for inserts and deletes, the full row image; for updates, only the columns that moved with before and after values

GET requests are not audited. Unbooking (soft delete) is no longer traceless: the removed entry’s full image survives as Audit Changes.

Scheduled jobs

Some changes are made by Sintropix on a schedule, with no request behind them. Their envelopes carry credentialType: "system", and route and method name the job instead of an endpoint:

Job	`method`	`route`	What it changes
Scheduled Source Feed sync	`CRON`	`source-feed-sync-sweep`	The Standing and Tax Period of landed DTEs, and the booking of new Invoices from the vendor’s Booking Template.

A sync you start on demand keeps the route and method of that request.

Status codes

Code	Meaning
200	Success
400	Invalid query parameters (bad type, a malformed `entityIds`, `from` after `to`, or a record history request without `tableName` and `rowId`)
401	Unauthenticated
404	Organization or Entity not found, outside your Organizations, or an Entity your API key is not confined to

Get Started

Ledger

Banking

Documents

Reports & Audit

Sources & Integrations

Platform

Sintropix Audit Trail API: Query Forensic Change History

List the Organization Log

List the history of one record

Response

What the trail captures

Scheduled jobs

Status codes

​List the Organization Log

​List the history of one record

​Response

​What the trail captures

​Scheduled jobs

​Status codes

List the Organization Log

List the history of one record

Response

What the trail captures

Scheduled jobs

Status codes