Yousign's API provides the ability to sign a Signature Request without requiring Signers to use Yousign's default signing flow (via iFrame or the Yousign platform). Instead, you can build your own signing interface, matching your needs.

This approach is ideal if:

• You want to create a fully customized signing experience.
• You need to interface with physical signature collection devices (e.g., a signature pad).
• You want to integrate the signing interface into a mobile or web application without embedding Yousign’s iFrame or redirecting to our platform.

📘

Why create your own Signature Interface ?

The vast majority of Yousign's customers want to have a turnkey signing interface which is easy to integrate. If you recognize yourself in this case, it's better to use the pre-built signing interface.

On the contrary, if you have very specific requirements, then building your signing interface is the best option. In this case, you take full responsibility for:

• implementing the signing interface according to the mandatory steps defined below
• proving that it is properly implemented
• providing Yousign with accurate information relating to the signing process and Signers.

What are the conditions to respect in order to build your own signing interface?

Pre-requisite

Before jumping to the tutorial below, make sure you:

• understand the Signature Request concept ;
• are familiar with the delivery_modeparameter ;
• have an active API trial or Scale plan.

Signature Request conditions

Please note Signature Requests must match the following criteria to be signed without using Yousign's signing interface:

• The Signature Request delivery_mode must be set to none to prevent any email from being sent to the Signer.
• All Signers of the Signature Request must have a signature_level set to Simple Electronic Signature (electronic_signature).
• No Approver should be added to the Signature Request.
• The Signature Request must not have the parameter signers_allowed_to_decline set to true, or any radio group or checkboxes.
• The Signature Request must not be linked to any Signer Document Request or Signer Consent Request

Signing interface mandatory steps

The signing interface you will create must:

• Allow Signers to fully review the document before signing.
• In case of a Signature Request with more multiple Signer, allow each Signer to see the signature of the Signers who have already signed the document.
• Collect the Signers authentication before the Signature collection.
• Allow Signers to explicitly agree to sign.
• Ensure that the Signers can download the signed document.

Step-by-step implementation guide

This guide will help you creating integrating Yousign's API capabilities into your own signing interface.

Step 1: Create and activate your Signature Request

To create your Signature Request, please follow this guide. The created Signature Request must respect the criteria listed above.

Step 2: Collect the Signer input and signature through your custom signing interface

This step is fully on your side, it relies on the signing interface you built. For this guide, we consider that you have created a signing interface in your mobile application composed of:

• a step allowing the Signer to view the Document to sign
• an optional step allowing the Signer to fill the Fields requiring a Signer input (a Text Field for example)
• a step allowing the Signer to receive the OTP by email
• a step allowing the Signer to fill in the OTP received by email and accept to sign the Document

Step 2.1 Retrieve and update Fields requiring Signer's input

If the Signature Request contains Fields requiring Signer input (e.g., Text Fields, Radio Groups, Checkboxes), retrieve them using this endpoint:

POST /signature_requests/{signatureRequestId}/documents/{documentId}/fields?signerId[eq]={signerId}

Once retrieved, update them with user-provided values using this endpoint:

/POST signature_requests/{signatureRequestId}/documents/{documentId}/fields/{fieldId}/answer.

⚠️ Important: you must populate all mandatory Fields with a value before proceeding to the authentication and signature.

Step 2.2 Trigger the authentication email or SMS

If a Signer has to be authenticated with anemail_otp or sms_otp, you will have to trigger the authentication email or SMS with this endpoint.

POST /signature_requests/{signatureRequestId}/signers/{signerId}/send_otp.

The Signer will receive the OTP by email or SMS depending on the chosen setting.

Step 2.3 Submit the Signer's OTP and trigger the signature

Once the Signer has received the OTP has provided it into your signing interface alongside their will to sign, you can finally send to Yousign the command to sign the Signature Request using this endpoint:

POST /signature_requests/{signatureRequestId}/signers/{signerId}/sign

This API call should contain:

• the Signer's OTP (if relevant in your context)
• the Signer's IP Address
• the Signer's Signature time
• the Signer's Signature image (optional)

Once this call is received by Yousign, the OTP will be verified and if valid, the Document will be signed.

Here is our retry policy on OTP codes:

• After 5 attempts, the OTP will not be valid anymore and will need to be sent again.
• After 10 minutes, the OTP will not be valid anymore and will need to be sent again.

Step 3: Provide access to the signed Document

After signing, Signers must be able to download their Document through your custom signing interface. You can download all the Documents of a Signature Request with one API call or download them one by one.