Skip to main content
ShieldID

Activity Ledger

Every look. Every click. On the record.

The Activity Ledger is an append-only record of everything that happens around a verification: who signed in, who opened a link, what the engine decided, who exported what. Entries can be added, never edited or deleted. Not by you, not by us.

Try the sample ledgerAPI reference

The ledger described here is the governance record that runs Trust Ledger today and is rolling out to ShieldID API accounts. Anything not yet recorded for identity verifications is marked Coming soon on this page.

Why it matters

A verification without a record is just an opinion.

Using an identity service adds a risk of its own: someone has to answer for who saw the applicant's ID and what was done with it. The ledger is how you answer.

For you

Prove what happened, in order, with the outcome. When a decision is questioned months later, the ledger is the evidence, and it outlives the ID images.

For your compliance lead

Answer a privacy request or an audit with a filtered export instead of a week of email. Every export is itself an entry.

For your applicants

Every view and download of a stored document leaves an entry, so "who saw my file?" has an answer the business can give. Per-image events for ID photos and a self-service view for applicants are coming soon.

What it records

The event vocabulary, in full.

Every entry uses one of these names, so a filter always means the same thing. Names are shown as they appear in the ledger.

Sign-in and access

Every way into the account, and every look behind the curtain.

LOGIN_2FA_CHALLENGED
A sign-in reaches the two-factor step.
LOGIN_SUCCESS
A sign-in completes.
FORENSIC_DETAIL_ACCESSED
Someone opens the network and device evidence behind an entry. It needs a written reason, and the request is itself recorded.

Verification requests

The applicant's journey, from link to consent.

SIGN_LINK_OPENED
The applicant opens their verification link.
EULA_ACCEPTED
The applicant accepts the terms before continuing.
TASK_CREATED / TASK_SENT
A verification request is created and sent, by a person or by an API key.
TASK_VIEWED / TASK_VOIDED
A request is fetched or cancelled through the API.

Records and exports

Anything that leaves the account leaves a trace.

DOCUMENT_VIEWED
A stored document is opened in the portal.
DOCUMENT_DOWNLOADED
A document is downloaded, in the portal or through the API.
DOCUMENT_EMAILED
A document is emailed to a recipient.
AUDIT_EXPORTED
An audit trail is retrieved through the API. Reading the record is itself recorded.

Account and API

Settings and credentials, with the actor attached.

SETTING_CHANGED
An account setting is changed through the API.
SESSION_CREATED / SESSION_REVOKED
An API session is opened or revoked.
ACCOUNT_MAILING_ADDRESS_UPDATED / BILLING_ADDRESS_UPDATED
Account details change.

Request timeline (per request, alongside the ledger)

Each request also carries its own timeline. It is a working record, not the append-only ledger, so we name it separately.

BIOMETRIC_VERIFIED / BIOMETRIC_FAILED
The verification engine reports the identity check passed or failed, with the check that failed.
RETENTION_PURGE / RETENTION_PURGE_FAILED
The retention sweep deletes a request's stored documents at the end of its window, or could not.
GDPR_ERASURE
Personal information is redacted under a right-to-erasure request.

On the way

Coming soon

The events that close the loop for identity verification specifically. We list them so you can hold us to them.

ID_IMAGE_VIEWED / ID_IMAGE_DOWNLOADED
Each time an ID image or selfie is opened or downloaded, by whom.
DECISION_RECORDED
The accept or decline your team records against a verification, with the reason.
API_KEY_CREATED / API_KEY_REVOKED
Key lifecycle events as ledger entries. Today they are stored with the key, not as entries.
VERIFICATION_VERIFIED / VERIFICATION_FAILED
Verification outcomes as append-only ledger entries for ShieldID API accounts. Today they are written to the request timeline.
IMAGE_PURGED
A receipt for every automatic ID-image purge.
Applicant view
A self-service page where the person verified sees who accessed their verification.
CSV export
A filtered export for auditors, in a spreadsheet. JSON export exists today.

Anatomy of an entry

Fourteen fields, every time. Then the evidence, on request.

An entry says who, what, on what, with what result, in plain words and in machine-readable form. The network and device evidence sits beside it, behind a logged request.

The entry

Actor type
Person, signer, system, admin or API key. An API key's actions carry the key's own id, so a script and a person are never confused.
Actor label
The name or email as it was at the time, not a live lookup that changes when people leave.
Action
The event name, from the fixed vocabulary above.
Category and severity
Auth, document, signing, task, account, security or system; info through critical.
Target
What the action was taken on: a verification, a document, a person, a setting.
Summary
One human sentence, written at the time.
Outcome
Success, failure or denied. A refused action is recorded as loudly as a successful one.
Metadata
Structured detail: API key label, environment (sandbox or production), request id, and more.
Timestamp
Server time, in order, never editable.

The evidence, behind a logged request

IP address and scope
Public, carrier-grade NAT, private, loopback or unknown, so a reviewer knows how much to trust it.
Network operator
Reverse DNS, registrant, ASN and whether the address belongs to a hosting provider.
Location
Country, region, city and postal code, with the accuracy radius and whether the data was stale.
Device
A short list of signals such as time zone, screen size, platform and languages, reduced to a stable SHA-256 fingerprint. No raw browser dump.
Reported address
What the browser itself reported, marked as unverified.

Evidence is enriched after the response is sent, never on the applicant's critical path, and is marked unenriched until it arrives.

Tamper evidence

We don't call it a blockchain, because it isn't one. It's a table the database refuses to let anyone edit.

Plain words about what protects the record, so your auditor can check our claims against our behaviour.

  • Append-only, enforced by the database

    A trigger on the governance table raises an error on any update or delete. Application code, administrators and we ourselves are subject to it.

  • One narrow, logged exception

    When an account is deleted, its entries are detached from the account rather than erased, and only if every other column is byte-for-byte identical. Nothing is truncated.

  • Writes go through a guarded function

    Entries are written by a database function with defined privileges, after a real incident in which row-level security silently swallowed writes. The fix is the reason the function exists.

  • Reading the evidence is an event

    Network and device detail cannot be read without a written reason of at least twelve characters, recorded under the reader's name as FORENSIC_DETAIL_ACCESSED.

  • Purging images does not touch the record

    ID images are purged on a short timer. Ledger entries are a separate record with no link to the images, so deleting an image never removes the entry that describes what happened to it.

Search and filter

Search it like a database, because it is one.

Every filter is validated server-side and scoped to your account. The filter lists show only values that actually occur, so you never search for nothing.

Actor
A person, or an API key by its id. Isolate everything one integration did.
Target
A verification, a document or a person. Everything that happened to this applicant's file.
Action
Any event name from the vocabulary.
Category, severity, outcome
Security events only, failures only, denied actions only.
Date range
From and to, to the second.
Free text
Across summaries, actor labels, target labels and actions. Deliberately never across raw metadata.

Export is JSON today: the full trail for a verification through the API, capped at five hundred rows, each retrieval recorded as AUDIT_EXPORTED. CSV export for customers is coming soon.

Try it

A sample ledger, fictional and searchable.

Filter, expand a row, open the evidence. The names and events below are invented for the demo; the field set and the behaviour are the real thing.

Activity Ledger

Sample data

18 entries shown.

  • 2026-09-16 · 13:41:22

    LOGIN_2FA_CHALLENGED

    Wren Halloway · Portal sign-in

    Success

  • 2026-09-16 · 13:41:58

    LOGIN_SUCCESS

    Wren Halloway · Portal sign-in

    Success

  • 2026-09-16 · 14:02:10

    SESSION_CREATED

    Onboarding widget (production) · API session 4a81

    Success

  • 2026-09-16 · 14:02:11

    TASK_CREATED

    Onboarding widget (production) · Verification for Ottoline Marchetti-Fife

    Success

  • 2026-09-16 · 14:19:47

    SIGN_LINK_OPENED

    Ottoline Marchetti-Fife · Verification link 7c19

    Success

  • 2026-09-16 · 14:20:12

    EULA_ACCEPTED

    Ottoline Marchetti-Fife · Verification consent

    Success

  • 2026-09-16 · 14:22:35

    BIOMETRIC_VERIFIED

    Verification engine · Verification for Ottoline Marchetti-Fife

    Success

  • 2026-09-16 · 14:22:39

    TASK_VIEWED

    Onboarding widget (production) · Verification for Ottoline Marchetti-Fife

    Success

  • 2026-09-16 · 15:07:03

    DOCUMENT_VIEWED

    Desmond Quillfeather · Result for Ottoline Marchetti-Fife

    Success

  • 2026-09-16 · 15:08:44

    DOCUMENT_DOWNLOADED

    Desmond Quillfeather · Result for Ottoline Marchetti-Fife

    Success

  • 2026-09-15 · 11:52:18

    SIGN_LINK_OPENED

    Barnaby Thistlewood · Verification link 3e77

    Success

  • 2026-09-15 · 11:55:02

    BIOMETRIC_FAILED

    Verification engine · Verification for Barnaby Thistlewood

    Failure

  • 2026-09-15 · 16:30:55

    FORENSIC_DETAIL_ACCESSED

    Perpetua Nakashima · Event evt-0012

    Success

  • 2026-09-15 · 09:14:31

    SESSION_CREATED

    Ines Valcourt-Brie · API key: Billing sync (sandbox)

    Success

  • 2026-09-14 · 17:45:09

    SESSION_REVOKED

    Ines Valcourt-Brie · API key: Legacy import (production)

    Success

  • 2026-09-14 · 10:22:47

    SETTING_CHANGED

    Clementine Ashgrove · Retention window

    Success

  • 2026-09-14 · 10:31:12

    AUDIT_EXPORTED

    Clementine Ashgrove · Activity Ledger export, 1 August to 14 September

    Success

  • 2026-09-14 · 03:00:04

    RETENTION_PURGE

    Retention sweep · 41 verifications past their retention window

    Success

Questions

Straight answers about the record.

See it with your own data

Run one sandbox verification. Then read what it wrote.

The fastest way to understand the ledger is to create an entry in it. Sandbox sessions are never billed.

Start free in sandboxBook a demo