What is it ?

Yousign's API provides the ability to pre-verify an identity for AES without requiring your Signers to upload their identity document on Yousign’s signing flow.

This is typically useful when your business process already includes upstream identity verification, and you do not want Signers to provide their identity document again at the time of signing.

Please note that pre-verifying an identity via this flow offers the same level of protection and security for your signatures as our regular AES, and complies with eIDAS + ETSI standards. The resulting signature certificate will still be of Advanced level, issued in the name of the Signer.

📘

Why pre-verify the identity of a Signer for AES ?

This feature is especially useful when trying to integrate Yousign in conversion sensitive user flows such as onboarding where you both want :

• Limited friction for the end user : only one document upload needed.
• Highly secured signature : Yousign’s Advanced Electronic Signature.

What are the conditions to respect in order to use Pre Identity Verification ?

📘

This feature is available only through a contractual agreement but at no additional cost if you already have purchased AES signatures. Please contact your customer representative to learn more.

Before jumping to the tutorial below, make sure you:

• understand the Signature Request concept.
• are familiar with the delivery_modeparameter.
• understand the Advanced Electronic Signature concept.
• are familiar with the Webhooks mechanism.

How to use Pre Identity Verification with Advanced Electronic Signature ?

Signature Request Preparation

1. Create a Signature Request.
2. Add each Signer to the Signature Request using the dedicated endpoint, and specify the following fields in the Signer payload:
   1. signature_level should be set at advanced_electronic_signature (see API reference);
   2. pre_identity_verification_required should be set to true (see API reference). This field is optional and its presence will activate the pre identity verification flow for the given Signer. Setting it to null will revert to classic AES mode.
   3. delivery_mode should be set to none. This is essential to ensure the pre identity verification flow. Setting this field to email or null while setting pre_identity_verification_required to true will result in an error.
   4. identification_attestation_id should be null
3. Activate the Signature Request.

Pre Identity Verification phase

This is the phase where you will be able to verify a signers identity by providing an identity_card, a passeport or a residence_permit.

For each Signer, pre-verify their identity using the dedicated endpoint (see API reference)).

At this step your Signer is in initiated status (see API documentation), and you have no access to the signature link that gives access to Yousign’s signing flow.

Handling Identity Verification results

Once you’ve successfully uploaded the identity to be verified, you will need to listen to Yousign’s Webhooks to continue the Pre Identity Verification Flow.

1. In case of a successful identity verification, Yousign will dispatch :
   1. The signer.identification_succeeded Webhook (see API reference).
   2. The signer.notified Webhook (see API reference).
2. In case of an unsuccessful identity verification, Yousign will dispatch :
   1. The signer.identification_failed Webhook (see API reference), inside the data attribute, you will have the ability to read the reason for the failure. (link)
   2. To fix one of the above errors, you can choose to :
      1. Re-upload an identity document using the dedicated pre-identity verification endpoint.
      2. Modify the Signer’s information using the Update Signer dedicated endpoint by specifying in the endpoint’s payload a different value for : first_name or last_name

         🚧

         Manual verification

         Following 3 failed identity verification attempts, you will have a last identity verification attempt which will be handled manually by our Provider. In case of a manual identity verification the delay to get the signer.identification_failed or signer.identification_succeeded could go up to 1 business day.

3. If this last identity verification attempt fails, Yousign will dispatch the following Webhook to warn you :
   1. signer.identification_blocked (see API reference) . In that case, we suggest you take a closer look at the identity document and Signer information provided before creating a new Signer and retrying a pre identity-verification flow.

Please note that you won’t be able to update the Signer’s information, after the signer.identification_blocked or signer.identification_succeeded Webhooks have been dispatched for that given Signer. This guarantees the information consistency until the end of the AES signing flow.

Signing Flow

1. Once a signer.identification_succeeded Webhook is dispatched for a given Signer, Yousign will dispatch the signer.notified Webhook in which you will find the link to the signing flow in the attribute : signers.signature_link
2. You can then share this link with your Signer, so that he can go through the simplified signing experience without needing to re-upload his identity documents.