---
updatedAt: 2026-11-02T15:10:26.000Z
agentTools:
  projectIndex: https://developers.youtrust.com/llms.txt
---

# Embedded Signing

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

# 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](https://developers.youtrust.com/docs/custom-experiences-new) 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

| Constraint       | Value                                                                                               |
| :--------------- | :-------------------------------------------------------------------------------------------------- |
| Signature levels | SES and AES. QES cannot be embedded                                                                 |
| Delivery mode    | `none`. Email delivery with an iframe causes unexpected behavior                                    |
| Embedded domain  | Your domains must be authorized first. See [iFrame security settings](https://developers.youtrust.com/docs/iframe-security-settings) |

## 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`

<AskAIBanner title="Needing support to embed the signing interface?" label="How do I embed the signing flow?" question="How do I embed the signing flow?" />

***

# Step 1: Initiate a Signature Request

* Endpoint: [Initiate a new Signature Request](https://developers.youtrust.com/reference/post-signature_requests-1) (`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.

```json Request
{
    "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](https://developers.youtrust.com/docs/custom-experiences-new).
* Remove `external_id` if you do not need to set your own identifier.

<Callout icon="💡" theme="default">
  Do not use the iframe signing flow with an email delivery mode. Combining the two causes unexpected behavior and errors. Learn more about [delivery modes](https://developers.youtrust.com/docs/delivery-mode).
</Callout>

Once created, upload the document to sign.

***

# Step 2: Upload a Document

* Endpoint: [Add a Document to a Signature Request](https://developers.youtrust.com/reference/post-signature_requests-signaturerequestid-documents-1) (`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 <a href="https://fields-position.vercel.app/test.pdf" target="_blank">sample document</a>.
* **Manual field positions**: give the absolute coordinates of the signature (page, position, width, height). Find coordinates with the <a href="https://placeit.youtrust.com/" target="_blank">Field Position tool</a>.

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

```curl cURL (with smart anchors)
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"'
```
```json Response example
{
    "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.

<Callout icon="🚧" theme="warn">
  Replace `{baseUrl}` and `{apiKey}` with the values for your environment. The API key must be created in the same environment as the Base URL you use.
</Callout>

Once the document is uploaded, add a Signer.

***

# Step 3: Add a Signer

* Endpoint: [Add a Signer to a Signature Request](https://developers.youtrust.com/reference/post-signature_requests-signaturerequestid-signers-1) (`POST /signature_requests/{signatureRequestId}/signers`)
* Content type: `application/json`

A Signer must have at least one [Signature Field](https://developers.youtrust.com/docs/signer-fields), the place on the document where they apply their signature. Learn more about [creating Fields](https://developers.youtrust.com/docs/fields-creation-new).

```json Request (without manual Fields)
{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "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
        }
    ]
}
```
```json Request (with Smart Anchors)
{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_email"
}
```

<Callout icon="🚧" theme="warn">
  Do not set `redirect_urls` when adding a Signer or on the Custom Experience. It disables the events sent by the iframe.
</Callout>

With the Signer added, activate the Signature Request.

***

# Step 4: Activate the Signature Request

* Endpoint: [Activate a Signature Request](https://developers.youtrust.com/reference/post-signature_requests-signaturerequestid-activate-1) (`POST /signature_requests/{signatureRequestId}/activate`)

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

The response includes a `signature_link` for each Signer.

<Callout icon="❗️" theme="error">
  The `signature_link` is sensitive: treat it like a user credential. Its validity is limited. See [how long a magic link stays valid](https://developers.youtrust.com/docs/limits-new).
</Callout>

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

***

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

<Callout icon="👍" theme="okay">
  We recommend using our Iframing SDK. It provides a high-level abstraction over the Youtrust application and simplifies the integration.
</Callout>

Load the script below in your page:

```html Minified version
<script src="https://cdn.yousign.tech/iframe-sdk-1.6.1.min.js" integrity="sha384-aZU9SeMGJ/Ff8fHahef90uY6eVlzpHGMJw5ob39ZauvdENhd8HkiBknF+uPZT+F5" crossorigin="anonymous"></script>
```
```html Unminified version
<script src="https://cdn.yousign.tech/iframe-sdk-1.6.1.js" integrity="sha384-z/LkmHmpy5cTNUXXhuStJCZ00JYQa/Pb0zjN8+Bkpaq6X+FmKkAJnMr6m+ldp7xX" crossorigin="anonymous"></script>
```

Or download the source and load the script manually: <a href="https://cdn.yousign.tech/iframe-sdk-1.6.1.min.js" download>compressed SDK (v1.6.1)</a> / <a href="https://cdn.yousign.tech/iframe-sdk-1.6.1.js" download>uncompressed SDK (v1.6.1)</a>.

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.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Youtrust SDK Iframe example</title>
    <script src="https://cdn.yousign.tech/iframe-sdk-1.6.1.min.js" integrity="sha384-aZU9SeMGJ/Ff8fHahef90uY6eVlzpHGMJw5ob39ZauvdENhd8HkiBknF+uPZT+F5" 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>
```
```css style.css
#iframe-container {
  width: 800px;
  height: 800px;
}

#iframe-container iframe {
  width: 100%;
  height: 100%;
}
```
```javascript script.js
const yousign = new Yousign({
  signatureLink: 'signature_link',
  iframeContainerId: 'iframe-container',
  isSandbox: false, // Set to true if you use the Sandbox environment
  iframeAttributes: {
    referrerPolicy: 'origin-when-cross-origin',
    title: 'Sign your lease agreement',
  },
});
```

For advanced SDK options, see the [iFrame SDK reference](https://developers.youtrust.com/docs/iframe-advanced).

<Callout icon="⚠️" theme="warn">
  In Production, embedding the Signing Flow is restricted for security reasons. You must explicitly configure how and where the Signing Flow can be embedded. 
  Go to your iFraming settings page to manage your settings.
</Callout>

<Callout icon="📘" theme="info">
  Youtrust is responsible for the accessibility of the signature flow displayed inside the iframe. As the integrator, you are responsible for the page that embeds it. See [Accessibility](https://developers.youtrust.com/docs/iframe-accessibility) for more details.
</Callout>

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:

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

<Callout icon="📘" theme="info">
  See the [iFrame SDK reference](https://developers.youtrust.com/docs/iframe-advanced#event-handlers) for the complete list of events and their callback data.
</Callout>

Your Embedded Signing integration is ready. 🎉

<SuggestedQuestions questions={["How do I embed the signing iframe?","What are the different embedding policies available?"]} />

<StillStuck heading="Didn't find what you were looking for?" subtext="Ask AI to help debug your integration." label="Ask AI" question="" />

# Sub pages

* [iFrame limitations](https://developers.youtrust.com/docs/iframe-limitations.md)
* [Integrate the iFrame](https://developers.youtrust.com/docs/iframe-advanced.md)
* [iFrame security settings](https://developers.youtrust.com/docs/iframe-security-settings.md)
* [Accessibility](https://developers.youtrust.com/docs/iframe-accessibility.md)