Identity event schema

The platform records every identity-axis transition in a conversation as an identity event. An integration that wants to mirror this audit data to its own systems (a security information and event management (SIEM) platform, a compliance-management tool, an internal audit warehouse) can read a conversation’s identity events through the API.

This page documents the wire schema. Programmatic access is per conversation: the endpoint returns every identity event for one conversation. The workspace-level aggregate view is an operator dashboard surface and is not part of the API-key interface.

Endpoint

GET /api/conversations/{conversation_id}/identity-events
Authorization: Bearer sf_live_v1_...

Required scope: conversations:read. The endpoint also accepts a dashboard session (operator JWT).

The endpoint returns all identity events for the conversation, oldest first. There are no query parameters.

Response:

{
  "events": [
    {
      "id": "11223344-5566-4788-99aa-bbccddeeff00",
      "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "conversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "occurredAt": "2026-05-13T10:14:32.000Z",
      "eventType": "factor_added",
      "factorCategory": "knowledge",
      "factorType": "kba_dynamic",
      "factorBoundToPrincipal": "44556677-8899-4a1b-8c2d-3e4f5a6b7c8d",
      "scopeDimension": null,
      "scopeValues": null,
      "evidenceRef": "kbv:lookup_orders",
      "promptVersion": "v3",
      "createdAt": "2026-05-13T10:14:32.000Z"
    }
  ]
}

Field reference

Field	Type	Notes
id	UUID	Stable across replays. Use this as the primary key in your mirror.
tenantId	UUID	Your account. Always present.
conversationId	UUID	The conversation the event belongs to. Join against your conversation records to recover workspace and channel context.
occurredAt	ISO-8601	When the event happened (runtime clock).
eventType	enum	One of the values in the Event types table below.
factorCategory	enum | null	knowledge / possession / inherence. Null for non-factor events.
factorType	enum | null	Specific factor (for example kba_dynamic, magic_link). See FactorType in @standfast/api-types.
factorBoundToPrincipal	UUID | null	Contact the factor binds to. Always present for factor_added / factor_failed.
scopeDimension	string | null	For assurance_level_reached: which dimension.
scopeValues	JSON | null	Payload, typically a list of permitted values.
evidenceRef	string | null	Audit handle pointing at the underlying mechanism (kbv:lookup_orders, magic_link:<uuid>, lockout:per_call:cap=3).
promptVersion	string | null	Version of the verification specialist system prompt at the time of the event.
createdAt	ISO-8601	Write time. Almost always equal to occurredAt within a few milliseconds.

Event types

eventType	Meaning	Required-fields contract
factor_added	A factor was successfully minted.	factorCategory, factorType, factorBoundToPrincipal, evidenceRef.
factor_failed	A factor attempt failed (wrong answer, bad signature, expired token).	Same as above.
kbv_question_asked	The verification specialist asked a knowledge question.	factorCategory='knowledge', factorBoundToPrincipal, evidenceRef='tool:<name>'.
kbv_question_passed	Caller answered correctly.	Same shape as asked.
kbv_question_failed	Caller’s answer did not match.	Same shape as asked.
identity_locked_per_call	Per-call wrong-answer cap hit.	factorBoundToPrincipal, evidenceRef='lockout:per_call:cap=N'.
identity_locked_per_24h	Per-identity 24h failure cap hit.	Same shape, evidence per_24h:cap=N.
ani_blocked	A caller-ID hit the per-ANI lockout.	scopeDimension='caller_ani', scopeValues=['+15551234567'].
assurance_level_reached	Caller’s combined factors reached a new assurance level.	factorBoundToPrincipal, scopeDimension='assurance_level', scopeValues=['identified'|'high-assurance'].
verification_not_configured	A gate fired but the workspace had no data sources attached.	scopeDimension='workspace_id', scopeValues=['<uuid>'].
verification_agent_context_used	The platform’s internal bypass was used to call a lookup tool during verification.	factorBoundToPrincipal, evidenceRef='tool:<name>'.

Retention

Identity events are retained for the workspace-configured period (default 24 months, range 3 to 84). Once an event ages past the retention cutoff it is hard-deleted on the daily sweep. Mirror promptly; the platform does not provide a recovery path for deleted events.

Erasure

If a data subject’s contact is purged via the GDPR Article 17 erasure endpoint, all of their identity events disappear from the API immediately. Your mirror should respect the same erasure request; run a periodic reconciliation pass that deletes mirror rows whose factorBoundToPrincipal no longer resolves on the platform.