Guides
Status PageRoadmapTestimoniesShare feedback

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.

Suggest Edits

❗️

Available on 21 July - We invite you to prepare this integration before this date. For our current API customers, we will wait for your approval before giving 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. Make sure you're well received the webhook signer.identification_blocked with the reason identity_mismatch to have the expected_first_name and the expected_last_name, the names read from the Signer’s ID document;
  2. 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;
  3. 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.

Updated 1 day ago