Table of contents

Matching cycles

The matching process consists of 3 matching cycles. The matching service should run each cycle in turn to attempt to match the user to the correct record in the local data source. Each matching cycle uses an increasing number of attributes from the identity provider to search for a match.

If, after 3 cycles, there’s no match, you can decide if you want to create a new account for the user.

The matching service uses limited information from the GOV.UK Verify Hub to run matching cycles. The limited information includes the persistent identifier (PID) and matching dataset.

Cycle 0

Cycle 0 is also known as the PID match. It works when a user has previously verified their identity with the same identity provider.

Cycle 0 matches the user’s hashed PID to an existing hashed PID in the local matching datastore(s) and returns a match.

Cycle 1

Cycle 1 is also known as the ‘matching dataset’ match. It works when Cycle 0 has failed to find a match and uses the matching dataset from the identity provider to check for possible matches.

Your Local Matching Service can use the details in the matching dataset to attempt to find a match between the user and their existing record. Your service’s matching rules should specify which details to use. For example, you should use historical verified data if offered by the identity provider and then use unverified historical data to tell the difference between candidate records.

If the Local Matching Service finds a single match, it creates a correlation between the hashed PID and the existing record in the local datastore(s).

The hashed PID is then written to the local matching datastore(s) so the next time the user attempts to use the service with the same identity provider, their record will be found with a Cycle 0 match.

Stop the matching process if Cycle 1:

fails to find a match and no additional attributes are available finds multiple matches and no additional attributes are available If Cycle 1 finds multiple matches and additional matches are available, continue to the next cycle.

Cycle 2

Cycle 2 matching uses additional attributes related to identity from another source such as a credit referencing agency or other government department to help the matching process. For example, an additional attribute could be whether the user qualifies for a Blue Badge.

GOV.UK Verify does not currently support Cycle 2 matching. No government connecting service has needed Cycle 2 matching so far. If you think your service needs Cycle 2 matching, contact the GOV.UK Verify team.

Cycle 3

If Cycle 1 finds more than 1 potential match, Cycle 3 asks the user for some additional information, for example driving licence number. The GOV.UK Verify Hub collects the additional information and sends it to the matching service. The Local Matching Service then uses it to refine the match. When the Local Matching Service finds a match, it saves the hashed PID in the matching datastore(s).

This cycle is defined in the government service policy and may not be needed for all matches. You should define the information the hub collects and how to use it for matching. For example, you decide how many pieces of additional information to request. If you request 2 pieces of information and the user can only provide 1 of them, your matching rules specify whether to match this user.

Use this cycle to enhance cycle 1 and not as an alternative to cycle 1.

Although it might seem more productive to run Cycle 3 straight away with the greatest number of attributes, it’s often less effective. Using Cycle 3 in place of earlier cycles can result in the Local Matching Service retrieving fewer possible matching records and incorrect records if one or more of the input attributes are incorrect.