Yousign's API provides the option to sign a Signature Request without asking Signers to go through Yousign's pre-made signing flow (in an iFrame or directly on Yousign's platform).

Indeed, you have the opportunity to build your own signing flow, matching your needs. This is particularly useful if:

• you want to build a custom signing flow
• you need to interface with physical devices to collect signatures (such as a signature pad for example)
• you need to integrate the signing flow into a mobile application, without having to use Yousign's iFrame or be redirected to Yousign's platform.

❓

Who should create their own signature flow?

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

On the contrary, if you have very specific needs, building your signing flow might be the best option. In this case, you take full responsibility for implementing the signing flow according to the mandatory steps defined below, proving that it is properly implemented, and providing Yousign with accurate information relating to the signing process and Signers.

How to sign a document without using the pre-made signing flow?

Before starting

Pre-requisite

Before jumping to the tutorial below, make sure you are familiar with the Signature Request concept and particularly the delivery_mode.

Conditions

Please note that signing documents without using Yousign's signing flow requires matching the following conditions:

• You need to have an ongoing trial on our API product or an active Scale plan.
• The Signature Request delivery_mode must be set to none.
• The Signature Request must not have any Approver.
• The Signature Request must not have the parameter signers_allowed_to_decline set to true
• The signature level must be "Simple eSignature".
• No Signer Fields can be used, except the Signature Field.

Signing flow mandatory steps

The signing flow you are going to create must match the following criteria:

• The signer must be able to read entirely the document to sign before giving their consent.
• The signer authentication must be done before the consent collection.
• The signer must be able to give their consent.
• Once the consent is given and the document signed, the signer must be able to download the signed version of the document.

Let's take a step-by-step guide to setting up a Signature Request and recreating the end-to-end signature scenario via our API.

Step 1: Initiate a Signature Request and upload a document to sign

Initiate a Signature Request with a delivery_mode set to none.

POST /signature_requests

application/json

{
    "name": "Signature Request",
    "delivery_mode": "none",
    "timezone": "Europe/Paris"
}

Then, upload the document to sign.

POST /signature_requests/{signatureRequestId}/documents

multipart/form-data

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/path/to/the/document/test.pdf"' \
--form 'nature="signable_document"'

Step 2: Add a Signer and activate the Signature Request

The signer's signature level should be set to simple eSignature. The authentication mode can be: OTP by email, OTP by SMS, or no OTP.

In our example, we are going to add a Signer with OTP by email.

POST /signature_requests/{signatureRequestId}/signers

application/json

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_email",
    "fields": [
        {
            "document_id": "{{documentId}}",
            "type": "signature",
            "page": 1,
            "width": 180,
            "x": 400,
            "y": 650
        }
    ]
}

Then, activate the Signature Request:

POST /signature_requests/{signatureRequestId}/activate

Step 3: Collect the signer consent through your own signing flow

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

• a step allowing the signer to view the document to sign
• 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
• an optional step allowing the signer to upload their signature image if this is an option you want to offer (this signature design has to be activated in your signature settings)

📘

Sign a document with the Signer signature image

If a Signature Request contains multiple Signers and you choose to upload their signature image, you must ensure that Signers can see the signature image of the Signers who have already signed the document.

For example, if Signer A signs first with signature image upload, then when Signer B reads the document before signing, they must see the signature image of Signer A on the document.

You can do so by downloading the document after each Signer has completed their signature.

The objective for you is to build your own signature flow and plug it with Yousign's API for the document signature. To do so, you will have to follow those two steps:

1. Trigger the OTP sending
2. Forward the OTP and trigger the signature

To send the email containing the OTP to the signer, you have to use this end-point and proceed as follows:

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

This step is not necessary if there is no OTP authentication set. Please note that the OTP message is not customisable.

Once the Signer has received the OTP and filled it into your signing flow, you can finally send to Yousign the command to sign the document.

This API call should contain:

• the OTP filled by the Signer
• the Signer's IP Address
• the Signer's consent 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.

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

application/json

{
    "otp": "123456",
    "ip_address": "192.0.2.146",
    "consent_given_at": "2024-04-19T22:10:00+00:00"
}

If you want to inform your signers with the right level of detail, 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 5: Make sure the Signer can access the signed document

Once the document is signed, the Signer must be able to access and download it through your flow. You can download all the documents of a Signature Request with one API call or download them one by one.