Digital ID Match

Digital ID Match is a service that allows your business to check whether one of their users (new or existing) has a Yoti account by sending the user’s email address or mobile number to our API.

Yoti will respond with the result as to whether the user has a Yoti Digital ID app account with a verified ID and if so, will enable the relying party to request that information securely via 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.

Search

To perform the search you must have an active Yoti service generated through the Hub, see here for details on how to generate the keys for this.

POST https://api.yoti.com/did

SDK integration

You will need to ensure the latest version of the Yoti backend SDK is installed.

// Get the Yoti Node SDK library via the NPM registry

npm install yoti

Once you have added the Yoti SDK to your project, the check can be performed as shown in the code snippet below:

const yoti = require("yoti");

const fs = require("fs");

​

const sdkId = "YOUR_SDK_ID";

const pem = fs.readFileSync("path-to-pem-file");

​

const body = {JSON_BODY}; //see below

​

const request = new yoti.RequestBuilder()

  .withBaseUrl("https://api.yoti.com/did")

  .withPemString(pem)

  .withEndpoint("/v1/matches")

  .withPayload(new yoti.Payload(body))

  .withMethod("POST")

  .withHeader("X-Yoti-Auth-Id", sdkId)

  .build();

Request body

{

  value: "someone@mail.com", // +447444 444 444 - Must be an email address or phone number

  notification: {

    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",

    },

  },

};

Response

A successful search will return a transaction ID and the result:

{

"id": "a-unique-transaction-id",

"result": "NO_ACCOUNT_FOUND"

}

Notifications

Push Notification

When performing the search, if the user has a Yoti Digital ID 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 app account and actions 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 service will have the same payload as defined by Cloud Events specification.