Handling Identity Mismatch Errors

If identification fails for mismatch reasons, we block the user to ensure that the next attempt is optimised on the basis of the information extracted from the identity document used.

❗️

For our API customers with the QES feature activated before 21 July, we need your validation to give you access to the feature.

Understanding the blocking mechanism after a name mismatch

When an identification attempt fails due to a mismatch between the information declared by the Sender and the data extracted from the Signer's ID document, the Signer will be automatically blocked. This mechanism ensures:

  • Optimized chances of success on the next identification attempt.
  • Reduced credit consumption when identification is bound to fail due to mismatched information.

You can see the errors concerned on this section. Please note that the firstname_missing error isn't concerned by the feature, as a Signer cannot have an empty first name. Once blocked, the Signer will see a waiting page and will be instructed to contact the Sender to resolve the issue.


First screen of the Signer where they need to contact the Sender

First screen of the Signer where they need to contact the Sender


First screen of the Signer where they need to contact the Sender

Waiting page for the Signer until the correction is made by the Sender


How to Correct a Signer's Information After a Matching Error

To allow the Signer to attempt identification again, the Sender/Integrator must follow this three-step process:

  1. When the identification fails, you will continue to receive the webhook signer.identification_failed as is already the case;
  2. In the case of a first name or last name error, and after the Signer clicks on the consent button to share the extracted information, you'll receive the signer.identification_blocked webhook containing the extracted first name (expected_first_name) and last name (expected_last_name);
  3. Unblock the Signer with the dedicated endpoint POST /signature_requests/{{signatureRequestId}}/signers/{{signerId}}/unblock_identification. Signers can't be updated if they've the blocked status;
  4. Update the Signer information with the names provided thanks to the webhook with the dedicated endpoint PATCH /signature_requests/{{signatureRequestId}}/signers/{{signerId}}.

Please note that the Signer must absolutely re-use the same identity document to ensure that the next attempt is optimised. We recommend that you use the webhook to check the extracted Signer's identity first and then accept the change.


✅ Important: The identification process cannot resume until these steps are completed (so the Signer will remain blocked until it is at least unblocked). Make sure you implement this logic to ensure a smooth user experience and prevent credit waste.