RESO Unique Licensee Identifier

How the ULI Works

The Problem

A licensee working listings in two neighboring MLSs holds an account in each, created independently and under names and office affiliations that rarely agree. Production splits across those records, a data share carries both, and a broker back office cannot reconcile them. Forms providers, lockbox systems and comparative market analysis tools each hold a different version of the same person.

Nothing identifies the records as one licensee, so each system creates its own identifier and none of them align.

The Unique Licensee Identifier is that identifier: one stable ID per licensed professional, carried alongside the IDs everyone already has rather than replacing them.

What a ULI Does Not Do

It does not merge records.

MLSs duplicate licensee records deliberately, to grant the access a licensee requires. Those duplicates are not a defect to be corrected; they are how the system works. A ULI links them. Each record keeps its own identity and its own local ID, and each also carries the ULI recording which person it belongs to.

Nothing is flattened and nothing is removed. A system that rolls up a licensee’s production can do so. A system with no use for it can ignore the field.

The Lifecycle

An Organization Joins

A participant loads its licensee data and runs the matcher against itself first. Internal duplicates surface before anything is shared, which is both useful on its own and the honest place to start: an organization sees what the matcher thinks about data it already knows well.

Many participants stop here for a while, deliberately. Local matching needs no network, no agreement with anyone and no disclosure.

A browser playground runs this local matching on sample data, or on a imported roster, and nothing loaded into the page leaves the browser.

One resolution thread: a broadcast, the replies, the consensus tally, then mint or adopt Broadcast One Note to the shared resolver collection, with the licensee's fields behind an OAuth2-protected link, not in the Note. Provider 8 Match → urn:…9f2c, score 1450 Provider 2 No match counts Other resolvers No match counts … replies accumulate over time A no-match reply counts toward consensus. Silence does not. Consensus At least floor(2/3 × R) replies are in, and every mandatory resolver is among them. R is the pool of certified, compliant and active resolvers, pinned at the moment of the broadcast. Mint No match in the replies. A new ULI is created and posted to the thread as a Create. It is the thread's only closing message. posted to the thread Adopt A match clears the bar. The existing ULI is bound to the originator's own records, locally. Nothing is posted to the thread. no thread message
One thread resolves one licensee. The originator broadcasts, each resolver answers from its own data, and once enough replies are in the originator mints a new ULI or adopts an existing one. Only a mint posts to the thread. Adoption changes no shared state, so it is silent (Specification, Sections 2.4 to 2.7).

A New Licensee Arrives

Membership staff enter a new licensee. Before the record is shared with anyone, it has to be specific enough to be worth asking about: at least two strong identifiers. A national association ID and a name. A license number and state, and a name. One alone is not enough, which is the rule that keeps a common name from matching half the state.

The Network Is Asked

The participant asks every other certified participant: do you already have this person?

This is where the design differs from what people expect. There is no central registry holding everyone’s licensees. Each participant searches its own data and answers for itself. The question travels; the data does not. What a participant shares, it shares with the parties it has authorized, over an authenticated connection, and only after the question has been asked.

Each one replies, and a reply of “no match” counts. That is not a formality. It is what lets the group reach an answer at all, and it is the difference between a participant that looked and found nothing and a participant that never looked.

An Existing Identifier, or None

Nobody does. Once enough participants have answered, the asking organization creates a new ULI. Not before – a new identifier is a claim that this person is not already on the network, and only the network can establish that.

Someone does. The asking organization adopts the existing ULI. Nothing is created, nothing is announced, and the other participant’s record is untouched. Both now point at the same person.

Two already exist. Two ULIs that turn out to be one licensee are reconciled, and neither of the two survives: both are excluded from matching, the merged details resolve on the network, and both originals retire into whatever that resolution returns (§2.7, §2.12.4). Each retired identifier keeps pointing at the target rather than disappearing, so anything that recorded either one still resolves. A single identifier does retire into another in the late-match correction of §2.12.3, which is a different case: there the test is a better match, a higher score, not a merge.

How the Network Decides

Matching is a question of evidence, and different identifiers carry very different amounts of it.

A national association ID is nearly decisive. A license number with its state is close. A full name narrows things considerably, until the name is Smith. An office name barely narrows anything on its own, but it is useful for telling two candidates apart.

So each matched identifier contributes according to how much it narrows the field, and the contributions add up to a score. The score is a threshold, not a probability – it says there is enough here, not this is 87 percent likely. Three outcomes:

Not a match too little in common to be worth anyone’s time
Needs review something real, not enough to act on. A person looks
Possible match enough evidence to take to the network

Two rules shape the scale, and both exist to stop a plausible-looking wrong answer:

One strong identifier never clears the bar on its own. That is the specification’s rule, and it is the one that matters: §2.4 states that identifiability “in practice requires at least two primary identifiers, since a single primary identifier cannot reach the threshold alone.”

The converse does not hold under the published numbers, and the gap is a known defect rather than a subtlety. At the specification’s threshold of 1300, Full Nickname at 650 plus License Number and State at 600 reaches only 1250, so two genuinely strong identifiers fall short. RESO has identified the threshold as the error and not the weights: 1250 is the sum of the two smallest identifiers that can co-match, which is the floor two primaries should clear by construction. The correction is proposed, not yet adopted.

Weak evidence cannot add up to strong evidence. An office, a shared surname and a matching middle initial can refine a decision between two candidates. No amount of it substitutes for a second strong identifier.

The weights and the threshold are published, identical for everyone, and treated as settings of the network rather than choices each participant makes. That is what makes one participant’s score mean the same thing as another’s.

Current status, and what is proposed rather than adopted. The specification publishes a weight set and a threshold of 1300, and makes both network parameters that RESO sets and may change independently (§2.9). Everything in this paragraph beyond that is RESO’s current thinking and is not in the specification: that the published weights are illustrative, carrying the right shape and ordering while the values are fitted against pilot data; and that the threshold is better derived from the weight set than chosen for it, so that it stays correct as the weights change. Under that derivation the threshold is 1250 rather than 1300. The specification’s §6 describes a different plan, a count-based scale over a versioned frequency table.

What Makes a ULI Trustworthy

A ULI carries its own proof. Each one is signed by the organization that created it, and anyone holding the identifier can check that signature offline, against that organization’s published key, with no lookup and no call back to anybody.

What this proves is narrow and worth stating precisely: a certified organization created this identifier. It does not prove the match was right, and it says nothing about the licensee. It means a fabricated or mistyped ULI cannot pass as real, which is the property that matters when an identifier travels far from where it was made.

For Implementers

Everything above is specified in the ULI Resolution Protocol, RCP-54. Section references are to that document.

The protocol is built from a small set of actions and two gates.

Actions. Broadcast a resolution request. Reply, with a match or a no-match. Mint a new identifier. Adopt an existing one. Supersede one with another. There is deliberately no “decline”: declining a proposed match is a rebroadcast with corrected criteria, because the participants who would confirm it need the correction, not a rejection (§2.7).

Gates. The identifiability gate keeps under-identified records off the network: a record must score highly enough that a full match could reach the threshold, which in practice means two primary identifiers (§2.4). The consensus gate governs creation: floor(2/3 × R) of the certified resolver pool must have replied, and every resolver the originator named as mandatory must have answered (§2.6).

Adoption is silent. Adopting an existing ULI posts nothing to the thread. A participant posts an outcome only when it changes shared state – creating, superseding, reconciling. This is counter-intuitive and it is deliberate (§2.7).

Transport. Resolution runs over ActivityPub using only standard Activity Streams 2.0 vocabulary, with no extensions (§2.2). An activity carries who acted and what it answers. Licensee records never ride in it: they sit behind an authenticated link in RESO Common Format (§2.1, §2.11).

Matching has two layers, and they are held to different standards. A participant’s search over its own data is measured on recall and precision, and how it searches is its own business. The score must reproduce the reference implementation exactly, on every published test vector (§3.1). Search finds candidates; scoring decides. Conflating them produces a number that cannot mean the same thing to two participants, because search relevance depends on what else is in the index.

Three layers, search, scoring and resolution, each held to a different certification bar 1 Search private Each resolver finds candidates in its own data. How it searches is its own business. Certified on recall and precision candidates 2 Scoring shared One engine, one published weight set and one frequency table, so a score means the same thing to every participant. Certified on exact parity with the reference an integer score, read against fixed bands: below 700 rejected, 700 to 1300 review, 1300 and above a possible match 3 Resolution the thread Broadcast, reply, consensus, then mint or adopt. A match reply carries its score in its payload. Certified on protocol conformance A search engine's relevance score depends on what else is in its own index, so it cannot be compared across organizations and never crosses the wire.
Three layers, three different standards. Search is each participant's own and is measured on recall and precision. Scoring is shared, and a conforming engine must reproduce the reference score exactly. Resolution is the thread, held to protocol conformance (Specification, Sections 2.9 and 3.1).

Certification is continuous. A participant proves conformance in a sandbox before joining, and is then monitored rather than periodically recertified: the daily liveness check samples recent threads and verifies the participant behaved correctly (§3.2).

Membership is public, resolution is not. A public, PII-free feed carries who is certified and what the network’s parameters are. The resolution conversations stay between authenticated participants (§2.10).

Three nested layers of access: network admission, thread access and record access 1 Network admission RESO decides Certification admits a resolver to the pool R: certified, compliant and active. 2 Thread access membership decides Every resolver following the collection receives every broadcast. No tokens are needed: delivery is free. 3 Record access the originator decides Reading the licensee's fields needs permission granted in advance, on an OAuth2-protected link, before the thread exists. Admission is never entitlement: a resolver receives every broadcast and reads only what it was authorized to read. RESO verifies resolvers; it does not authenticate traffic.
Three layers of access. RESO admits resolvers to the pool, membership delivers every broadcast to every resolver, and the originator decides, per thread and in advance, who may read the licensee's fields (Specification, Sections 2.1, 2.10 and 3.1).