Investigate a decision in the audit trail (API)

Find a validation, read why Tracer decided, and check that the audit trail is intact.

Participants

Your institution. Your system reads the decisions and their audit trail.
Tracer. Keeps the validations and their audit events, and verifies the audit chain.

Your system can call the Tracer API with a valid credential. See the Tracer integration guide.
The decision came from a validation request of your system, or from a Midaz transaction that Tracer checked. See Validate a transaction before the ledger and Check Midaz transactions with Tracer.

#	From	To	Message	Lerian API	What happens
1	Your institution	Tracer	Lerian API	`GET /v1/validations`	List the validations. Filter by `decision`, `account_id`, `matched_rule_id`, `exceeded_limit_id`, `scheme`, `transaction_id`, `start_date` and `end_date`.
2	Tracer	Your institution	Lerian API	Response to step 1	Tracer returns the matching validations, newest first, with a cursor for the next page.
3	Your institution	Tracer	Lerian API	`GET /v1/validations/{validation_id}`	Read one validation.
4	Tracer	Your institution	Lerian API	Response to step 3	Tracer returns the transaction context you sent, the decision, the matched rules and the limit usage.
5	Your institution	Tracer	Lerian API	`GET /v1/audit-events`	List the audit events of the validation. Set `resource_id` to the `validationId`.
6	Tracer	Your institution	Lerian API	Response to step 5	Tracer returns the audit events.
7	Your institution	Tracer	Lerian API	`GET /v1/audit-events/{audit_event_id}/verify`	Verify the audit chain up to the event.
8	Tracer	Your institution	Lerian API	Response to step 7	Tracer returns `isValid`, the number of events it checked and, when the chain fails, `firstInvalidId`.

The verification returns isValid as true for the chain up to the event.

The audit event of a validation request, on POST /v1/validations or POST /v1/validations/rules-only, has the type TRANSACTION_VALIDATED.
Without start_date and end_date, both lists cover the last 90 days.
The API has no route to change or delete a validation or an audit event.
Tracer records each check of a Midaz transaction as a validation with the transactionId of the transaction, and without a TRANSACTION_VALIDATED event. The capacity it holds appears as audit events with the resource type reservation, and GET /v1/validations/{validation_id}/reservations lists each hold with its state. A validation of a transaction with more than one source lists the outcome of each source in sources.

Situation	What you see	What to do
The validation is older than the default window.	An empty list.	Widen `start_date` and `end_date`.
The audit chain fails the check.	`isValid` is `false`.	Send the response to Lerian support.