Identifiers and identity

An identifier is how an activity refers to a person or a thing of theirs. The service keeps every identifier it sees, normalised into a join key, and the identity service links identifiers that belong together into persons, from evidence the activities carry.

Types

Type	Example	Normalised into
email	Ana.de.Vries@gmail.com	lower case, trimmed, plus-addressing stripped, dots removed on providers that ignore them: anadevries@gmail.com
phone	06 24681357	E.164 with the owner's country as the default region: +31624681357
device	evx_web_8f21c0	scoped to the owner: a device is never joined across organisers
barcode	TK-4471	with its namespace (the issuing system): uniqueness only holds within one
chip	WB-0093	with its namespace (the provider)
external	an id in another system	with its namespace

The value as typed is kept beside the key for display and search; the key is only for joining. A value that cannot be normalised (an email without a domain) quarantines the activity with unparseable_identifier. A phone number that parses but is nobody's, a placeholder such as 06 12345678 or 06 00000000 (seven or more of one digit or consecutive digits in a row), is dropped from the activity instead and counted as placeholder_identifier: the activity goes on with its other identifiers, and the number never enters the identity graph. A key longer than the identity tables can hold (80 characters by default, such as an email address of more than 80) is dropped the same way and counted as identifier_too_long.

On the wire

"identifiers": [
  { "type": "email", "value": "ana@example.com", "role": "buyer" },
  { "type": "barcode", "value": "TK-4471", "role": "holder", "namespace": "weeztix" },
  { "type": "email", "value": "ana@example.com", "role": "buyer", "confidence": 40 }
]

• role says what the person is to the activity: buyer, holder, … Attribute observations and geo blocks attach to the identifier with the role they name; the evidence rules below are written in terms of roles.
• confidence (0 to 100, default 100) says how sure the sender is that the identifier belongs to the activity's subject. The buyer's email on a ticket that may be held by someone else travels with confidence 40.
• namespace is required to make barcodes, chips and external ids unique.

Fields in features of class identifier (the email on subscribed_newsletter) become identifiers too and leave features. anonymous_customer_id becomes a device identifier.

Evidence, claimed and verified

Some activities say that two of their identifiers belong to the same person. The catalogue holds those rules per activity (shown on each page as "identity evidence"): issued_ticket links the holder's barcode to the buyer's email; completed_order links the shop visitor's device to the buyer's email (verified, weak: a browser can be shared); activated_wristband links a chip to a barcode; identified links a device to an email.

Each piece of evidence is an edge with a strength and an assurance:

• Verified edges come from sources that prove the link: an order, a scan, a clicked mail link, a double opt-in. They merge people.
• Claimed edges come from something typed: an email in a form, with a browser key. A claim attaches a new identifier to a person but never merges two existing people. A verified edge on the same pair promotes it; a claim that stays unverified for 30 days is retracted.

Merges are deterministic. Splits happen when an edge is retracted, and the service splits the person only if nothing else holds it together. Retractions come from a human through the identity API, with two exceptions the service makes itself. When a supplier corrects a record (a typo in the buyer's email), it retires the old identifier when nothing else ever evidenced it, and lists it for review otherwise. And when a ticket is personalised to someone other than its buyer, it retracts the barcode's edge to the buyer's email (strength 40, there "until personalised"): a ticket bought for a friend links the friend to the ticket, not the friend to the buyer.

Every identifier seen gets a person, alone if nothing connects it, so a device that only ever viewed pages is still in the map.

Erasure

Erasing an identifier removes it from the map, retracts its edges, deletes its identifier and attribute rows and the tracking calls that carried it, and tombstones it so later evidence is ignored.