Integration guide

AI Tools

Digital ID Match is a service that allows a business to check whether one of its users (new or existing) has a Yoti Digital ID app account by sending their unique attributes to our API.

Yoti will provide a response indicating whether the user has a Yoti Digital ID app account with a verified ID. If the user has such an account, Yoti will allow the relying party to securely request that information through a Yoti QR share.

Users will receive a push notification on their phone that a search has been carried out. We will also send a POST notification to an endpoint that you specify in your request.

Important

You must inform the user that you are carrying out this search. Users are able to opt out of the search from within their Yoti Digital ID app account.

Search

Request Access

To use Digital ID Match, the service needs to be enabled for your organisation by the Yoti team. Please contact your account manager or our support team to request access.

POST https://api.yoti.com/did/v2/matches Authorization: Bearer {access_token} { "attributes": [ { "name": "PHONE", "value": "+447444444444" } ], "notification": { "url": "https://example.com/notification", "method": "POST", "verifyTls": true, "headers": { "ANY-HTTP-HEADER": "the-header-value" } }, "metadata": true }

Request body

{ "attributes": [ { "name": "PHONE", "value": "++447444 444 444" }, ... ], "notification": { // required "url": "https:/example.com/notification?example=query-param", "method": "POST", "verifyTls": true, "headers": { "ANY-HTTP-HEADER": "the-header-value", "ANOTHER-HTTP-HEADER": "another-header-value" } }, "metadata": true }

Key	Required	Description	Example Value
attributes	Yes	An array of attributes to match the user against.	melissa.peterson@yoti.com +447444444444
notification	Yes	If the user indicates within the app that the search was not triggered/opted in by them. You can specify any headers needed.
url	Yes	The URL of your notification endpoint. Include any query parameters here.	https://yoti.com
method	Yes	The API method for the notification. Default value is POST	POST
verifyTls	No	Confirms that your notification endpoint needs TLS verification.	true - Boolean
headers	No	Any HTTP headers for your notification endpoint.
metadata	No	Whether to include additional information related to the matched account(s) ⚠️ Note: Even if requested, metadata will only be included in the response if the user consented for it to be included	true - Boolean

Attributes

There are many different attributes that can be matched against. You can include multiple attributes in a search

Attribute	Description	Value
EMAIL	The user's email address	melissa.peterson@yoti.com
PHONE	The user's phone number - this must include the country code	+447444444444
DOB	The user's Date of Birth - this must be in yyyy-mm-dd format	2000-01-01
FULL_NAME	Full name as it appears on the user's ID document	Melissa Peterson
POST_CODE	Post code from the user's UK address	EC3N 1RE
DOC_NUMBER	The document number from the user's ID document	0123456789
DOC_ISSUER_COUNTRY	The issuing country of the user's ID Document, this must be the ISO 3-letter country code as specified here	GBR
DOC_TYPE	The document type	PASSPORT

These must be used in specified sets

Set #0 - Phone
Set #1 - Email
Set #2 - Phone + Full Name + DOB
Set #3 - Email + Full Name + DOB
Set #4 - Full name + DOB + Postcode
Set #5 - doc type + issuing country + doc number
Set #6 - Full name + DOB + doc number

Response

A successful search returns a 201 response containing the transaction ID and any matched attributes/attribute sets.

Individual attributes that do not match are omitted from the response.

For attribute sets, if at least one attribute does not match, the entire set is returned as NOT_MATCHED.

If no attributes match at all, a 204 No Content response is returned.

{ "matches": [ { "id": "VisRarSFaZG1x5rYTssgS6FswgOHgH77XcSuI7SYFC601YCp88DWt9jjFwOUKZA6", "product": "YOTI", //Or POST_OFFICE "verified": true, "results": [ { "attributes": ["PHONE"], "result": "MATCHED" }, { "attributes": ["EMAIL"], "result": "MATCHED" }, { "attributes": ["PHONE", "FULL_NAME", "DOB"], "result": "MATCHED" }, { "attributes": ["EMAIL", "FULL_NAME", "DOB"], "result": "MATCHED" }, { "attributes": ["FULL_NAME", "DOB", "POST_CODE"], "result": "MATCHED" }, { "attributes": ["DOC_NUMBER", "DOC_ISSUER_COUNTRY", "DOC_TYPE"], "result": "MATCHED" }, { "attributes": ["FULL_NAME", "DOB", "DOC_NUMBER"], "result": "MATCHED" } ], "metadata": { "account_created": 5, "id_document_count": 2, "first_nfc_passport_added": 2, "first_id_document_added": 4, "successful_gpg45_identity_profile_share": true } } ] }

{ "statusCode": 204, "headers": { "date": "Mon, 01 Jan 2026 00:00:00 GMT", "server": "yoti-edge-proxy", "strict-transport-security": "max-age=31536000; includeSubDomains; preload", "x-request-id": "1beaad0ea3d46e0a3681905208e5b2b2", "connection": "close" }, "data": null }

{ "id": "Yzt0sbVOSauDWPwMQvumjQ", "status": 400, "error": "INVALID_PAYLOAD", "message": "An error message from the server" }

{ "id": "Yzt0sbVOSauDWPwMQvumjQ", "status": 500, "error": "FAILED_DIGITAL_ID_MATCH", "message": "An error message from the server" }

Transaction ID

Transaction ID

You should record this ID and securely store it together with the searched email address or phone number. If a user reports on their Digital ID app that the search was not triggered by them, you can cross-reference this information with the webhook notification (detailed below).

Field	Description	Example
id	transaction ID for the search	VisRarSFaZG1x5rYTssgS6FswgOHgH77XcSuI7SYFC601YCp88DWt9jjFwOUKZA6
product	The digital ID product that returns a match	Yoti
verified	Will return match if the Yoti Digital ID app account has a verified ID	true
attributes	The attribute names requested	PHONE
result	Confirmation if the specified attribute matches	MATCHED, NOT_MATCHED, NOT_APPLICABLE
Metadata	Details on the user's account

Status	Response
201	Created
204	No match found
400	Bad Request
500	Server Error

Notifications

Push Notification

When performing the search, if the user has a Yoti Digital ID app account, they will receive a push notification informing them that the search has taken place. This will also appear in their Activity tab. They will then have the option to confirm whether or not they agree to this.

Example:

The Company name will be the external name of your Yoti application used for performing the match. The Company URL will be the URL in the application settings. See here for information on the application set-up.

Webhook Notification

Within the body, you must specify an endpoint for a POST notification. This notification is sent to your backend when a user receives the push notification to their Yoti Digital ID app account and indicates that it is not them.

{ "specversion": "1.0", "id": "Y2el8YXnCTN6d2xa8ENADdKkE21EdNK-_CuSZrkmdHA4UdqsSD2mAXuCwLlZmZDw", "type": "com.yoti.connect.event.did.not-me", "source": "urn:yoti:connect:did", "time": "2025-05-27T12:55:04.199Z" }

Any webhook notification sent via our Digital ID Match service will have the same payload as defined by Cloud Events specification.

Value	Details
specversion	Version number of the Events Spec
id	The unique transaction ID from the initial response
type	Yoti notification type
source	Yoti service sending the notification
time	The time the user confirmed it wasn't them in UTC.

Last updated on

Was this page helpful?