Guides
Status PageRoadmapTestimonies

Integrate the Signing Flow within your application using iFrames

Learn how to integrate the Signing flow in your own application.

Suggest Edits

In order to integrate the Signing Flow within your application using an iframe, you have to follow the steps:

1. Initiate the Signature Request

2. Upload the document to sign

3. Add a signer

4. Activate the Signature Request

5. Use the SDK to embed the Signature Flow in an Iframe

6. Trigger actions during the signature flow

📘

Choose your environment

In the following requests, you should prefix all the endpoints with the correct Base URL according to the environment you want to use. If you are in trial you can only use the Sandbox.

Sandbox Base URL: https://api-sandbox.yousign.app/v3
Production Base URL: https://api.yousign.app/v3

Step 1: Initiate a Signature Request

You will now initiate a Signature Request and specify the Signers.
The attribute delivery_mode is set at none because we do not want Yousign to send an email to notify the Signer in this scenario. If we had some, Approvers or Followers wouldn't have been notified either. More details about the delivery_mode can be found here.

POST /signature_requests

application/json

{
    "name": "The name of your Signature Request",
    "delivery_mode": "none",
    "custom_experience_id": "{{customexperienceId}}",
    "external_id": "{{externalId}}"
}
  • Replace {{customexperienceId}} if you want to customize the Custom Experience or delete this optional attribute
  • Replace {{externalId}} if you want to set your own id or delete this optional attribute

💡

We strongly recommend not to use the iFrame signing flow with an email delivery mode

iFraming should only be used with the delivery mode none, doing otherwise could conduct to unexpected behaviours and errors.
More information about the delivery mode can be found here.

Step 2: Upload a Document

Then, you prepare the document (PDF) you want to request a signature on.

To place the visual signature field on the document you have two solutions:

  • using "smart anchors": you will place text placeholders like {{s1|signature|200|100}} directly in the source documents and will automatically detect the position and size of the signature. You can use this sample document: test.pdf

  • using manual fields positions: you will give absolute coordinates of the signature (page, position in the page, width and height). You can use this tool to find the coordinates: Field Position

To sign the document, you need to add at least one signature_field

You can now proceed to the document upload.

POST /signature_requests/{signatureRequestId}/documents

multipart/form-data

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/Users/user/test.pdf"' \
--form 'nature="signable_document"' \
--form 'parse_anchors="true"'

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

{
    "id": "1bfddb98-91f5-4120-87a9-068be05da257",
    "filename": "test.pdf",
    "nature": "signable_document",
    "content_type": "application/pdf",
    "sha256": "3df79d34abbca99308e79cb94461c1893582604d68329a41fd4bec1885e6adb4",
    "is_protected": false,
    "is_signed": false,
    "created_at": "2021-09-15T12:52:39+00:00",
    "total_pages": 1,
    "is_locked": false,
    "initials": null
}

When you upload your document, you can choose the alignment and position of the area that will contain the initials on the document. If you add several signers, they will each have their initials written on the document. You can choose their alignment and position on the document when uploading your document.

🚧

Do not forget to replace {baseUrl} and {apiKey} with the proper value.
The API Key should be created with the same "Environment" as the Base URL you use.

🚧

Most of the time you should not set the Content-Type manually to multipart/form-data, it will be managed directly by your HTTP client and include the correct boundary for your form.

Step 3: Add a signer

Then, you have to add a *Signer's to your Signature Request.
A Signer must have at least one Signature Field. The signature Field represents the place on the document where the Signer will apply his signature. A Signature Field must be associated with a document. You can learn more about Fields creation here.

POST /signature_requests/{signatureRequestId}/signers

{
    "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
        }
    ]
}

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_email"
}

🚧

Don't set the redirectUrls when adding a signer or on the custom experience, it disabled the events sent by the iframe.

Step 4: Activate the Signature Request

POST /signature_requests/{signatureRequestId}/activate

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/activate' \
--header 'Authorization: Bearer {apiKey}'

❗️

The signature_link is sensitive information and should be treated like a user credential (password for example). Its validity is limited to ensure its security. How long is this magic link valid?

Step 5: Use the SDK to embed the Signature Flow in an iFrame

👍

We recommended to use our Iframing SDK. It simplifies the integration of the signer flow by providing an high level abstraction with the Yousign application.

Load the script below in your page to use our SDK.

<script src="https://cdn.yousign.tech/iframe-sdk-1.6.0.min.js" integrity="sha384-/7MD1voOOzWVz7FmgeMwmmd1DO85Mo0PkkxdYd9j2wDGzGDGRG/phgnL0c9Xyy52" crossorigin="anonymous"></script>

<script src="https://cdn.yousign.tech/iframe-sdk-1.6.0.js" integrity="sha384-R+s/yjLK/cbrNa3CN+AZ62oJ0C2aGzcSsGYpTnX/SI89pmrEGlAWUCdzkR2RuVR6" crossorigin="anonymous"></script>

Or you can download the source file and load the script manually on your page :

Download the compressed SDK (v1.6.0)
Download the uncompressed SDK (v1.6.0)

You will use the signature_link from the /activate request response for each signer to initialize the SDK.
Here is an example of how the SDK works to integrate your signature.
Don't forget to set the property isSandbox to true if you use the sandbox environment.

<!DOCTYPE html>
<html>
  <head>
    <title>Yousign SDK Iframe example</title>
    <script src="https://cdn.yousign.tech/iframe-sdk-1.6.0.min.js" integrity="sha384-/7MD1voOOzWVz7FmgeMwmmd1DO85Mo0PkkxdYd9j2wDGzGDGRG/phgnL0c9Xyy52" crossorigin="anonymous"></script>
    <link href="style.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div id="iframe-container"></div>
  </body>
  <script src="script.js" type="text/javascript"></script>
</html>

#iframe-container {
  width: 800px;
  height: 800px;
}

#iframe-container iframe {
  width: 100%;
  height: 100%;
}

const yousign = new Yousign({
  signatureLink: signature_link,
  iframeContainerId: 'iframe-container',
  isSandbox: true, //To set if you use the sandbox environment
});

For more information about iFrame, you should go to this page about SDK iFraming.

❗️

For security reasons, iFrame is available only in production on whitelisted domains. To add your domains, please get in touch with our support.

Please note that it is also possible to whitelist a subdomain (https://subdomain.domain.com) or all subdomains of a domain by using a wildcard, for example https://*.domain.com. In this case all subdomains of domain.com will be authorized.

Step 6: Trigger actions during the signature flow

Along the Signer Flow, we send events that you can catch in the parent of the iframe. The SDK provide a set of methods that simplify event usage.

📘

See Iframe SDK reference about how event can be caught.

Most of the time you will wait for the success event to trigger a following action (closing the iframe or redirecting the user to another page).
Here is an example about how to catch the success event :

yousign.onSuccess((data) => {
  console.log("Signer has successfully signed");
});

Events which can be listened :

  • started: Signer opened the Signature Flow
  • success: Signer has signed successfully the document.
  • error: Signer has encountered an error while signing
  • ping: (Healthcheck, for debug only) Signature Request is loaded (event sent every 5 seconds)
  • declined: When Signer declined the signature
  • signature.done: When Signature is completed (all Signers have signed the Signature Request)

Updated 7 days ago