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 email address or phone number looked up

On a call and by email, the answer also holds the number or address the lookup was called with, at the field the operator designates on the same lookup’s row (the field with the phone number on By phone number, the field with the email address on By email address). oHallo uses the record only when that field holds it; see The value in the answer.

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 are compared on the Person-ID wherever the record holds one. A Danish record that holds no Person-ID is compared on its CPR number instead, on a MitID connection at Idura whose operator has ticked CPR number in MitID logins: the customer types the number during the MitID login, the provider checks that it belongs to them, and the verification link compares it with the number on your record. Return it as a string of ten digits, with or without the hyphen (DDMMYY-NNNN); separators are removed before comparison, and a value returned as a JSON number is read as absent. A workspace’s setup can also use the CPR number 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, the national identity number path and, on the lookup’s tool, the field that holds the email address or the phone number. 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.

oHallo withholds a designated identifier by its field name across the whole connection, so each identifier field needs a name of its own. A designation is refused with a 422 whose message says what to change when every segment of its path is an array index, punctuation, an MCP envelope key such as text or a text key such as $t, when its name is a common one such as id, value or number, or when a customer reference, a security question or a created-record field on the same connection reads from a field of that name. When an element’s text sits under a key such as #text, _text, $t or #cdata, the element carries the name: customer.CPR.#text names CPR, and the whole element is withheld.

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 a call, where the approval is 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 verification link, by email compared with the record that holds the sender’s address and in chat bound to the record the customer named, 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, and by email only when your lookup by the sender’s address returns the same customer reference again. The hash is deleted when the link completes, is declined or is replaced, and when an unused link is closed after it expires.

The verification read is the one call that receives the designated identifiers. In every other answer from a tool on the same connection, oHallo replaces the value of each field whose name matches a designated identifier with [REDACTED], at any depth of a JSON text payload and of structuredContent, before the answer reaches the assistant or any record. Names match regardless of letter case and punctuation, so cpr, CPR and c_p_r are the same field. Return the identifier only under its designated field, in a JSON text payload or in structuredContent. Design a tool that needs to know which customer it serves to take the customer reference as its input.

A national identity number is never stored, never logged, never placed in a model’s context, and never written to tool-call records: every call on a connection with a designated identifier, the verification read included, is exempt from response capture, 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 verified another way. 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. By email and in chat the record needs the identifier the verification link compares, by email on the lookup that takes the sender’s address; on a call, the identifier the provider’s app approval addresses by, on the lookup that takes the calling number. Both lookups are read on the connection that holds the tool the request needs. A record without the one the channel needs is not verifiable by eID there: a request that needs identified falls back to the workspace’s other methods, a link to the email address on the record, or Caller ID or the email sender address on a channel where it is set to “Identifies the customer”, and a request that needs high-assurance goes to a colleague. 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. 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.