Why embed the signing flow

Sending a Signer to another domain in the middle of your product is where funnels leak. Embedded Signing keeps the signature inside your own page and gives your front-end events it can react to.

• Keep the Signer in context. No redirect, no new tab, no "is this the right site?" moment.
• React the moment the Signer is done. The SDK emits started, success, declined and signature.done, so your own funnel can advance without polling.
• Keep your own layout. The signing flow sits in a container you size and position.
• Keep your branding. Combine it with a Custom Experience so the embedded interface matches the page around it.

Typical use cases

• An onboarding funnel where the contract is step 4 of 6 and the user must land on step 5 without leaving.
• A back-office tool where an operator prepares a document and has a walk-in customer sign on the spot.
• A mobile web app that cannot afford a redirect out of the session.

Before you choose it

How to integrate the Embedded Signing

To integrate the Signing Flow within your application using an iframe, follow these 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.

➡️ In the requests below, prefix every endpoint with the Base URL for the environment you 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

• Endpoint: Initiate a new Signature Request (POST /signature_requests)
• Content type: application/json

Set Signers on the Signature Request. The delivery_mode field is set to none because you do not want Youtrust to email the Signer in this scenario. Approvers and Followers, if any, would not be notified either.

{
    "name": "The name of your Signature Request",
    "delivery_mode": "none",
    "custom_experience_id": "{{customexperienceId}}",
    "external_id": "{{externalId}}"
}

• Remove custom_experience_id if you are not using a Custom Experience.
• Remove external_id if you do not need to set your own identifier.

Once created, upload the document to sign.

Step 2: Upload a Document

• Endpoint: Add a Document to a Signature Request (POST /signature_requests/{signatureRequestId}/documents)
• Content type: multipart/form-data

Prepare the PDF you want signed and place its visual signature field with one of two methods:

• Smart anchors: place text placeholders like {{s1|signature|200|100}} directly in the source document. Youtrust detects their position and size automatically. Try it with this sample document.
• Manual field positions: give the absolute coordinates of the signature (page, position, width, height). Find coordinates with the Field Position tool.

The document needs at least one signature_field for the Signer to sign.

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"'

{
    "id": "1bfddb98-91f5-4120-87a9-068be05da257",
    "filename": "test.pdf",
    "nature": "signable_document",
    "content_type": "application/pdf",
    "is_signed": false,
    "total_pages": 1
}

If you add several Signers, each gets their own initials on the document. You choose their alignment and position when you upload the document.

Once the document is uploaded, add a Signer.

Step 3: Add a Signer

• Endpoint: Add a Signer to a Signature Request (POST /signature_requests/{signatureRequestId}/signers)
• Content type: application/json

A Signer must have at least one Signature Field, the place on the document where they apply their signature. Learn more about creating Fields.

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

With the Signer added, activate the Signature Request.

Step 4: Activate the Signature Request

• Endpoint: Activate a Signature Request (POST /signature_requests/{signatureRequestId}/activate)

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

The response includes a signature_link for each Signer.

Use this link to embed the Signature Flow in an iframe.

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

Load the script below in your page:

<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 download the source and load the script manually: compressed SDK (v1.6.0) / uncompressed SDK (v1.6.0).

Use the signature_link from the activation response to initialize the SDK for each Signer. Set isSandbox to true when you use the Sandbox environment.

<!DOCTYPE html>
<html>
  <head>
    <title>Youtrust 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, // Set to true if you use the Sandbox environment
});

For advanced SDK options, see the iFrame SDK reference.

Once the iframe is embedded, listen for signature events.

Step 6: Trigger actions during the signature flow

The SDK exposes methods to catch events from the Signer Flow in the parent of the iframe.

Most integrations wait for the success event to close the iframe or redirect the Signer:

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

Your Embedded Signing integration is ready. 🎉