Audit trail

Every state-changing call in this API writes an audit entry. So does every read of a document. The trail is append-only: nothing in it is edited or removed, including entries about things that were later deleted.

An entry

{
  "id": "d61f9a37-5b28-4c40-9e13-7a4c8d2f6b95",
  "agency_id": "4f0c9d2e-1b7a-4c33-9d55-2c8e7a1b6f40",
  "user_id": "a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90",
  "user_name": "Hon. Maria Alvarez",
  "user_email": "judge.alvarez@example.gov",
  "warrant_id": "9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10",
  "action": "SIGN",
  "resource_type": "warrant",
  "resource_id": "9d2b6e14-6f1a-4a1c-9c0e-6f5f4b3a2d10",
  "details": {"from": "SUBMITTED", "to": "SIGNED"},
  "ip_address": "198.51.100.24",
  "user_agent": "eCourtDate-Integration/1.4",
  "created_at": "2026-08-19T15:04:51Z"
}

user_id is the person, resolved from X-On-Behalf-Of when the call came through an integration. That is the whole reason the header is mandatory on writes: an entry that named only the integration would not answer the question anyone actually asks, which is who did this.

Actions

Group	Actions
Lifecycle	CREATE, UPDATE, SUBMIT, SIGN, REJECT, DELETE
Routing	ASSIGN, REASSIGN, UNASSIGN, ESCALATE
Removal	TRASH, RESTORE
Access	VIEW, DOWNLOAD, UPLOAD
Sessions	LOGIN, LOGOUT
Collaboration	COLLABORATE

Agencies that use eCourtDate's virtual call feature also see call and recording actions in the trail. They are outside the surface these guides describe, but they appear in the same list, so treat action as an open vocabulary and do not fail on a value you do not recognize.

One warrant's history

curl -s "$BASE/audit/warrants/$WARRANT_ID" -H "x-api-key: $API_KEY"

The full history of one application, in order, from creation through every transition. This is the call to make when someone asks what happened to a warrant, and it is the natural backing for a timeline view.

One person's activity

curl -s "$BASE/audit/users/$USER_ID?limit=100" -H "x-api-key: $API_KEY"

Searching

curl -s "$BASE/audit/logs?action=SIGN&limit=100" -H "x-api-key: $API_KEY"

Parameter	Filters by
action	A single action
resource_type	warrant, template, user, file, and so on
user_id	The person who acted
warrant_id	One application
skip, limit	Paging

Entries come back newest first. For a periodic export, page by skip within a single filtered query and record the newest created_at you have seen, so the next run can stop when it reaches it.

Reading the audit trail requires the audit:read scope, and the caller's role must permit it. It is the most sensitive read in the API: it names people, addresses, and what they did.

What it is good for

• Answering a challenge. Who applied, who reviewed, when, and from where.
• Compliance reporting. Signed warrants per month, time from submission to signature, escalations that fired.
• Detecting the quiet failure. A rise in ESCALATE entries says the bench is not being reached in time, long before anyone files a complaint.

What it is not

It is not a change feed. There is no cursor or subscription, and polling it to drive workflow will be both slow and wrong under load. Read the resources themselves for current state, and read the trail for history.