Returning a national identity number

When a workspace offers verification with a national eID (MitID, BankID), oHallo proves the caller with the scheme and binds the approval to a record in your own system. Both halves read fields from the answer of the same lookup tool described in The customer lookup contract. This page is the contract for those fields: which ones are read, what format they take, what happens to the values, and the failure your tool must be designed for.

The system of record is whatever system your tool fronts: a support desk, a billing system, an ERP, a bespoke service. oHallo never asks what kind of system it is; it asks only that the designated fields are in the answer.

The fields

The customer reference, always

Every eID verification ends by binding the caller to one of your records, and the value it binds is the customer reference: the same stable identifier the lookup contract requires, at the field path the operator designated. Proving who a person is grants nothing by itself; proving one person does not entitle them to another person’s record. The reference is what turns a proven person into your customer.

The scheme’s person identifier (Denmark)

Danish MitID mints a durable person identifier, the Person-ID: a UUID that the customer’s own MitID login returned and your system stored against the record. It is the same value at every broker and it is not the CPR. Return it exactly as your login integration stored it: braces, dashes and letter case are normalised before comparison, so {1373c272-b61a-4cb5-88b2-9c44883fe62f} and 1373c272b61a4cb588b29c44883fe62f are the same identifier.

If your system has never stored one, because the customer has never authenticated at your own eID login, that record is in the bootstrap case described under the failure section below.

The national identity number, where the scheme keys on it

Swedish BankID mints no person identifier: its own API returns a personnummer, a name and signature material, and nothing else identifies the person. Swedish records are therefore keyed on the personnummer, and a Swedish eID verification reads that field. Return it in either written form: ten digits with the usual separator (YYMMDD-NNNN, where + in place of the hyphen marks a person aged one hundred or more) or twelve digits (YYYYMMDDNNNN). Both are expanded to the canonical twelve digits before comparison, so either form on your record matches the same person.

Danish records need no national identity number for the eID comparison. A workspace’s setup can additionally use one to address an approval prompt, where the record lawfully holds it; the operator designates that field the same way and the same privacy contract applies to it.

Designation against your declared outputSchema

oHallo never guesses field names. The operator designates, in the workspace settings, where each of these values sits in your tool’s answer: the customer reference path, the person identifier path, and the national identity number path. The pickable paths are derived from your tool’s declared outputSchema, and a designation naming a path outside the declared schema is rejected at save time. So declare one: a tool without a declared outputSchema forces the operator to type paths by hand, and a wrong path then surfaces only at runtime, as a recorded lookup outcome on the designation instead of an error at save time.

What happens to the values

The customer reference is the only value oHallo keeps: it lands on the contact as the external record link. The identifiers exist to be compared or relayed, once, and then dropped:

• On an approval pushed to the customer’s own app, the record-held identifier is relayed to the scheme to address the prompt, and nowhere else.
• On a record-bound verification link, the identifier your tool returned is normalised and hashed when the link is created; at completion the scheme-returned identifier is normalised, hashed and compared against it, and the raw values are discarded. A verification completes only when the two are equal.

A national identity number is never stored, never logged, never placed in a model’s context, and never written to tool-call records: the verification read is exempt from response capture by construction, and the identity ledger names the scheme (eid:dk_mitid), never the identifier. Your system is told nothing it did not already hold; every identifier in the flow is one your own record supplied.

The failure your tool must be designed for

A record without the designated identifier is not verifiable by eID. That is the normal state for every customer who has never authenticated at your own eID login, not a fault, and it is handled as a first-class answer: eID declines for that caller and verification falls back to the workspace’s other methods, security questions bound to your data or a link to the email address on the record. No identifier is ever guessed, and no different record is picked.

Three rules follow for your tool:

• Return no value rather than a placeholder. An absent field or an empty string declines cleanly. A value that cannot be an identifier, a name or an internal id, is refused before it reaches a scheme and is recorded against the designation as field_missing.
• Return the customer reference even when the identifier is absent. The other verification methods still need the record link, and a record that resolves without an identifier belongs to exactly the caller who will use them.
• Store the identifier when your own login learns it. A customer who authenticates at your own eID login gives your system the value to store; from then on the record verifies by eID here too.

Until the operator designates the fields at all, eID is unavailable for the workspace, the settings say why, and nothing reaches your tool.

Scheme availability

Danish MitID verifies callers in the current release. Which schemes a workspace can offer is derived per workspace from the scheme configuration and the designated fields together, and shown in the workspace’s National eID settings. The field contract on this page is the same for every scheme.