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
Section titled “Endpoint”GET /api/conversations/{conversation_id}/identity-eventsAuthorization: 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": "possession", "factorType": "magic_link", "factorBoundToPrincipal": "44556677-8899-4a1b-8c2d-3e4f5a6b7c8d", "scopeDimension": null, "scopeValues": null, "evidenceRef": "magic_link:c9f8e7d6-b5a4-3210-fedc-ba9876543210", "promptVersion": null, "evaluationSummary": null, "createdAt": "2026-05-13T10:14:32.000Z" }, { "id": "22334455-6677-4899-aabb-ccddeeff0011", "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "conversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210", "occurredAt": "2026-05-13T10:16:05.000Z", "eventType": "eid_approval_denied", "factorCategory": "possession", "factorType": "eid_verified", "factorBoundToPrincipal": "44556677-8899-4a1b-8c2d-3e4f5a6b7c8d", "scopeDimension": null, "scopeValues": null, "evidenceRef": "eid:dk_mitid", "promptVersion": null, "evaluationSummary": "subject_mismatch", "createdAt": "2026-05-13T10:16:05.000Z" } ]}Field reference
Section titled “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, eid_verified). |
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, eid:dk_mitid). |
promptVersion | string | null | Version of the verification specialist system prompt at the time of the event. |
evaluationSummary | string | null | The result recorded with the event, in words. It never contains the customer’s answer or the identifier a verification compared. On kbv_question_passed and kbv_question_failed it says whether the answer matched the record. On verification_not_configured it begins level_unreachable: when the request needs a level no method on the conversation reaches, and record_link_unavailable: when the request needs the customer’s own records, or their company’s, and the National eID verification that opens them cannot be offered in the conversation, each followed by its reason as listed under Results on verification_not_configured below, and on older rows it can name the lookups that could not form a question, each with its reason. On factor_failed it reads not minted: approval_declined_earlier when an email link was opened after the verification in that conversation had been declined. The results on the eID event types are listed under Results on eID events below. Null when the event records no result. |
createdAt | ISO-8601 | Write time. Almost always equal to occurredAt within a few milliseconds. |
Event types
Section titled “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), or a completion arrived after the conversation’s verification was declined and minted nothing. | 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 calling number hit the per-ANI lockout. | scopeDimension='caller_ani', scopeValues=['+447700900123']. |
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 and no method on the conversation could verify the caller for it. | 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>'. |
eid_approval_requested | An approval prompt was pushed to the customer’s own eID app (MitID, BankID). | factorCategory='possession', factorType='eid_verified', factorBoundToPrincipal, evidenceRef='eid:<scheme>'. |
eid_link_issued | An eID verification link was minted for the customer to open at their own timing: by email compared with the record that holds the sender’s address, in chat bound to the record the customer named. No scheme contact happens at mint; this row is the request’s accountability record until a completion writes an outcome. A provider_error row is not a completion: the link stays usable, and a later outcome row for it can follow. | Same shape as eid_approval_requested. |
eid_approval_granted | The customer approved and the returned token verified. evaluationSummary is account_ambiguous when the customer’s record named their company in a form that ties none. | Same shape as eid_approval_requested. |
eid_approval_denied | The customer declined in their app, or a completed verification did not match the record or carried no identifier the record is compared on, or, after a verification link, was a login with a business identity, or the customer cancelled the login on the scheme’s own login page. After a verification link, evaluationSummary names the reason, and on either path it reads account_conflict when the customer’s record names a different company than their verification already in force, and identity_kind_conflict when the customer holds a verification of the other kind, private MitID or MitID Erhverv, already in force. A first-class answer, not a fault. A decline or a verification that did not match ends app requests and verification links in the conversation; a cancelled login (provider_error:access_denied) ends nothing and is not final for its link. | Same shape as eid_approval_requested. |
eid_approval_expired | The scheme’s window closed with no answer, or the completion could not be confirmed, or, after a verification link, the scheme ended its login without a result (provider_error:<word>, not final for its link). | Same shape as eid_approval_requested. |
The five eID event types share one shape: possession category, factor type eid_verified, and an evidenceRef naming the scheme (for example eid:dk_mitid). The identifier the verification bound to, a scheme person identifier or a national identity number, never appears in an identity event.
Results on verification_not_configured
Section titled “Results on verification_not_configured”evaluationSummary | Meaning |
|---|---|
level_unreachable: no method on this conversation reaches the level the request needs | No verification method on the conversation reaches the level the request needs. |
record_link_unavailable: the request needs a record link, and National eID cannot supply it in this conversation | The request needs the customer’s own records, and National eID verification cannot be offered in the conversation. |
record_link_unavailable: the request needs the company's records, and the customer's record names no company | The request needs the records of the customer’s company, and the customer’s record names no company. |
record_link_unavailable: the sender's address is on no record, and no link is bound to the record the request names | By email, a request that needs high-assurance names a record, and the address the customer wrote from is on no record of the system the request needs. No verification link is sent. |
record_link_unavailable: no lookup by email address with the field that holds the address, on the connection that refused the call | By email, a request that needs high-assurance names a record, and the connection that holds the tool the request needs has no lookup by email address, with the field that holds the address, to find the customer’s own record with. No verification link is sent. |
Results on eID events
Section titled “Results on eID events”eventType | evaluationSummary | Meaning |
|---|---|---|
eid_approval_requested | approval requested via <provider> | The provider the approval was sent through, for example approval requested via idura. |
eid_link_issued | link issued via <provider> | The provider the link was issued for, for example link issued via idura. |
eid_approval_denied | subject_mismatch | After a verification link, the scheme proved a different person than the record names. |
eid_approval_denied | identifier_claim_absent | After a verification link, the scheme’s answer did not carry the identifier the record is compared on. |
eid_approval_denied | business_identity_refused | After a verification link, the customer logged in at the scheme with a business identity, such as MitID Erhverv, on a link that compares no company registration number. The verification bound no one. |
eid_approval_denied | account_conflict | The scheme proved the customer against their record, and the record names a different company than the customer’s earlier verification of the same record that is still in force. Nothing was verified or bound, and the conversation continues as the workspace’s setting for what follows a decline says. |
eid_approval_denied | identity_kind_conflict | The scheme proved the customer, and the customer holds a verification of the other kind that is still in force: a MitID Erhverv login beside a private MitID login, or the reverse, which oHallo never joins on one customer. Nothing was verified or bound, and the conversation continues as the workspace’s setting for what follows a decline says. |
eid_approval_granted | account_ambiguous | The customer was verified and tied to their own record. The record named their company in a form that ties none (more than one company, an empty value, or a value with the form of a personal identity number), so no company was tied. |
eid_approval_expired | approved at the scheme; not completed: record_link_write_failed | The scheme approved the customer, and the verification was not completed. The customer is asked to verify again. |
eid_approval_expired | approved at the scheme; not completed: approval_declined_earlier | The scheme approved after the verification in the conversation had been declined, so nothing was verified or bound. |
eid_approval_denied | provider_error:access_denied | After a verification link, the customer cancelled the login on the scheme’s own login page. Not final: the link stays usable, and a later outcome row for the same link can follow. |
eid_approval_expired | provider_error:<word> | After a verification link, the scheme ended its login without a result. <word> is the error code the provider returned, when it is one of the codes of RFC 6749 section 4.1.2.1 or OpenID Connect Core section 3.1.2.6 other than access_denied, and other for any other code. Not final: the link stays usable, and a later outcome row for the same link can follow. |
<provider> is the connection’s provider id, such as idura. A link’s provider_error row is written at most once in 15 minutes. Every other eID event carries evaluationSummary: null.
The lookup the verification read records its own outcome on the lookup’s row, shown on the Customer records page: customer_ref_refused when the record’s customer reference is not kept (see the customer lookup contract), account_ambiguous when the record names the customer’s company in a form that ties none, and record_mismatch when the field designated for the email address or phone number holds another one than the lookup was called with, in which case the verification leaves that record aside.
Retention
Section titled “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
Section titled “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.