Create new user accounts (optional)¶

If Verify fails to identify the user, you can enable your service to create a new user account.

You must obtain explicit user consent before creating a user account.

Create new user accounts using the hashed persistent identifier (PID) and a subset of attributes from the matching dataset listed below.

Prerequisites

Configure your MSA to create user accounts.

In the YAML configuration file, enter your local matching service ‘accountCreationUrl:‘

On the Request access to an environment form:

Enter the fully qualified URL that will receive your Unknown User Attribute requests from the environment

Select any of the following user attributes you require for your service

FIRST_NAME
FIRST_NAME_VERIFIED
MIDDLE_NAME
MIDDLE_NAME_VERIFIED
SURNAME
SURNAME_VERIFIED
DATE_OF_BIRTH
DATE_OF_BIRTH_VERIFIED
CURRENT_ADDRESS
CURRENT_ADDRESS_VERIFIED
ADDRESS_HISTORY
CYCLE_3
Note

User Accounts can only be created with the user’s current ‘NAME’ and ‘Date of Birth’ data. ADDRESS_HISTORY will return any address known to be associated with the user, within the last three years.

Message flow

This diagram shows the message flow for creating user accounts. In this example, the service has been set up to create user accounts when matching fails.

User account creation

For more details, see:

Note

In this example, all 3 matching cycles previously failed to find a match for the user in the government service records.

Your local matching service sends a no-match response to the hub via the MSA.
The GOV.UK Verify hub:

checks that your matching service supports the creation of user accounts

identifies the attributes you previously said your service needs to create a user account

If your service supports the creation of user accounts, the hub sends a query to the MSA. It contains the:

matching dataset

hashed PID

level of assurance

list of attributes to extract from the matching dataset

The MSA POSTs the following JSON to the local matching service’s account creation URI endpoint:

[{
 "hashedPid": "<string value>",
 "levelOfAssurance": "<the level of assurance, e.g. LEVEL_1>"
}]

Optionally, the local matching service stores the hashed PID and level of assurance in the local matching datastore.

You’ll need to create a correlation between the user account and the hashed PID, so a returning user can match with cycle 0. You can choose to store the hashed PID at this point and create a correlation between the user account and the hashed PID at step 9. Alternatively, you can create the user account, store the hashed PID and set up the correlation at step 9.
The local matching service sends a JSON response to the MSA:
```
{ "result": "success" }
```
or
```
{ "result": "failure" }
```

Note

As shown above, success and failure must be in lower case.

Note

A user account isn’t created at this point. The final response the hub sends to your service will contain the attributes you need to create a user account.

The local matching service may return { "result": "failure" } if:

the level of assurance in the JSON request sent by the MSA is lower than the level of assurance required by the service

there are exceptional circumstances, such as maintenance, when you want to suspend user account creation

The MSA extracts the required attributes from the matching dataset.
The MSA sends the extracted attributes, the hashed PID and the level of assurance to your service via the GOV.UK Verify hub.

Note

The MSA must send this data via the GOV.UK Verify hub, to respect the following identity assurance principles:

user control - users must give informed consent for their information to be used to create an account; they must also be allowed to check their information before you create the account

data minimisation – the service receives only the restricted set of attributes it needs, not the full matching dataset.

For more information see the Identity Assurance Principles.

The government service:
- creates a user account using the attributes extracted from the matching dataset
- sets up a correlation between the user account and the user’s hashed PID