Reidentification (ReID)

Reidentification lets a previously verified user confirm their identity again without repeating the full document verification flow. X-Faces captures new biometric data and compares it with the biometric data from the user’s reference verification.

Typical use cases include account recovery, high-risk actions, periodic identity checks, and confirming that the original account holder is still present.

Prerequisites

Before starting ReID:

• the user must already be verified;
• the user’s reference challenge must contain usable biometric data;
• a default ReID template must be configured for your project;
• the user should have a notification_url configured if you want to receive the result by callback.

Supported modes

The mode is defined by the ReID template configured in X-Faces.

Mode	User action	Checks
selfie	Takes a new selfie	Face comparison with the reference verification
liveness	Completes a liveness capture	Liveness and face comparison
selfie_liveness	Completes selfie and liveness captures	Liveness and face comparison using both captures

Integration flow

1. Create and fully verify the user through the standard verification flow.
2. Store the returned u_uuid in your system.
3. When identity confirmation is required, open the ReID URL for that user.
4. The user completes the configured capture steps in the X-Faces interface.
5. X-Faces processes the attempt and sends its result to the user’s notification_url.
6. Use reidentified from the callback as the result of this ReID attempt.

Start ReID

Open the following URL in the user’s browser or embedded X-Faces frame:

GET https://api.x-faces.xyz/v1/user/reidentify/<u_uuid>

Replace <u_uuid> with the X-Faces user identifier returned when the user was created.

You can pass the same UI query parameters that you use for the standard verification page, for example:

GET https://api.x-faces.xyz/v1/user/reidentify/<u_uuid>?lang=en

If the request is valid, X-Faces creates a ReID challenge and redirects the browser to the capture interface.

Repeated requests

Only one active ReID challenge can exist for a user at a time. If the endpoint is opened again while a challenge is active, X-Faces reuses that challenge instead of creating another one.

Callback

When processing is complete, X-Faces sends an HTTP POST request to the user’s notification_url.

{
  "u_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "your-internal-user-id",
  "challenge_id": "cb2d6c7f-4cf2-48ac-9221-d4f876d65763",
  "challenge_template_id": "cf976c42-ef31-41ce-814a-99dc2fb211f0",
  "action_type": "reid",
  "reidentification_mode": "liveness",
  "reidentified": true,
  "liveness": true,
  "reference_challenge_id": "28d0a39d-9517-47e8-9c6f-1ddbfd3f7748",
  "rejection_reasons": [],
  "score": 0.93,
  "created_at": "2026-09-25T10:15:00Z",
  "updated_at": "2026-09-25T10:15:08Z"
}

Field	Type	Description
u_uuid	string	X-Faces user identifier
external_id	string	User identifier in your system
challenge_id	string	Identifier of this ReID attempt
challenge_template_id	string	ReID template used for the attempt
action_type	string	Always reid for a ReID callback
reidentification_mode	string	selfie, liveness, or selfie_liveness
reidentified	boolean	Whether the new biometric data matches the reference verification
liveness	boolean or null	Liveness result; may be null in selfie mode
reference_challenge_id	string or null	Challenge used as the biometric reference
rejection_reasons	string[]	Machine-readable reasons for an unsuccessful attempt
score	number, optional	Face comparison score when available
created_at	string	ReID challenge creation time in ISO 8601 format
updated_at	string	Last ReID challenge update time in ISO 8601 format

Respond with HTTP status 200 after accepting the callback. X-Faces retries delivery when the callback cannot be delivered successfully, so your handler must be idempotent. Use challenge_id as the idempotency key.

Note

reidentified describes only the current ReID attempt. It does not replace or reset the user’s original verified status.

Rejection reasons

An unsuccessful attempt has reidentified: false and one or more of the following values in rejection_reasons:

Code	Meaning
reidFaceMismatch	The newly captured face does not match the reference verification
reidLivenessFail	The liveness check failed
reidReferenceMissing	Reference biometric data is missing
reidReferenceInvalid	Reference biometric data cannot be used for comparison
reidInvalidSteps	The configured ReID capture steps are not supported
reidNoResult	X-Faces could not produce a valid ReID result

Treat technical reasons such as reidReferenceMissing, reidReferenceInvalid, reidInvalidSteps, and reidNoResult separately from a biometric mismatch. They usually require a fallback flow or assistance from X-Faces rather than an immediate risk decision.

Start errors

If X-Faces cannot start ReID, the response contains result: false and a message describing the problem.

Message	Action
Invalid user uuid	Check the supplied u_uuid
User is not verified	Complete the standard verification flow first
Reference challenge is missing	Verify the user again or contact X-Faces
Reference challenge has no biometric data	Run a new full verification that captures biometric data
Reidentification template is not configured	Ask X-Faces to configure a default ReID template
Verification stopped temporary	Retry later or contact X-Faces

Partner-side recommendations

• Start ReID only from an authenticated session in your application.
• Keep u_uuid server-side and associate it with your internal user record.
• Make callback processing idempotent by challenge_id.
• Check both action_type === "reid" and reidentified === true before approving the protected action.
• Apply a short expiration window to your business action even if the ReID result is successful.
• Provide a fallback route for failed or technically incomplete attempts.