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.
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

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:
- Make sure you're well received the webhook signer.identification_blocked with the reason
identity_mismatch
to have theexpected_first_name
andthe expected_last_name
, the names read from the Signer’s ID document; - Unblock the Signer with the dedicated endpoint
POST /signature_requests/{{signatureRequestId}}/signers/{{signerId}}/unblock_identification
. Signers can't be updated if they've theblocked
status; - 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