# Embedded Signing

> Embedded signing allows you to have users sign signature requests directly on your app or website. Read the setup steps and requirements here.

# Embedded Signing Walkthrough

Give your users the ability to sign documents directly on your app or website using Dropbox Sign's embedded signing feature. The [hellosign-embedded](https://npmjs.com/package/hellosign-embedded) library adds the signing experience to your site using an iFrame.
The documentation below describes requirements and setup steps for the embedded signing flow. Take a look at our [premium branding guide](/api/manual-reference-pages/premium-branding) to learn more about customizing your app's embedded signing.

## Preliminary

1. [Create an API app](https://app.hellosign.com/oauth/createAppForm) (login required)

<Warning title="Important" icon="fa-light fa-circle-exclamation">
  The API app's domain name controls where the embedded iFrame can be opened. Embedded signing will only be possible on this and it's subdomains. However, you can use `skipDomainVerification` to embed requests created using `test_mode`.
</Warning>

2. Save your API app's Client ID and [API Key](/api/api-reference-authentication#api-key), which you'll need to use this feature.

## Try Dropbox Sign Embedded

To get a feel for how our library works, you can use our [Embedded Testing Tool](/docs/additional-resources/embedded-testing-tool) to quickly test any of our Embedded flows without having to write a single line of JavaScript.

You can request a sample document, or use the custom `sign_url` that you'll generate in the [Server Side](#server-side) section below.

## Server Side

The very first step is to create an embedded signature request from your backend using our API and then fetch the associated url that will be used in the iFrame. Note that embedded signature requests use a different endpoint than non-embedded signature requests.
Endpoint: [/signature\_request/create\_embedded](/api/signature-request/create-embedded)

### Creating an Embedded Signature Request

<Tabs>
  <Tab title="Payload">
    <CodeBlock>
      ```json title="Default Example"
      {
       "client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
       "title": "NDA with Acme Co.",
       "subject": "The NDA we talked about",
       "message": "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
       "signers": [
         {
           "email_address": "jack@example.com",
           "name": "Jack",
           "order": 0
         },
         {
           "email_address": "jill@example.com",
           "name": "Jill",
           "order": 1
         }
       ],
       "cc_email_addresses": [
         "lawyer1@dropboxsign.com",
         "lawyer2@dropboxsign.com"
       ],
       "file_urls": [
         "https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
       ],
       "signing_options": {
         "draw": true,
         "type": true,
         "upload": true,
         "phone": false,
         "default_type": "draw"
       },
       "test_mode": true
      }
      ```

      ```json title="Grouped Signers Example"
      {
        "client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
        "title": "NDA with Acme Co.",
        "subject": "The NDA we talked about",
        "message": "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
        "grouped_signers": [
          {
            "group": "Group #1",
            "order": 0,
            "signers": [
              {
                "email_address": "jack@example.com",
                "name": "Jack"
              },
              {
                "email_address": "jill@example.com",
                "name": "Jill"
              }
            ]
          },
          {
            "group": "Group #2",
            "order": 1,
            "signers": [
              {
                "email_address": "bob@example.com",
                "name": "Bob"
              },
              {
                "email_address": "charlie@example.com",
                "name": "Charlie"
              }
            ]
          }
        ],
        "cc_email_addresses": [
          "lawyer1@dropboxsign.com",
          "lawyer2@dropboxsign.com"
        ],
        "file_urls": [
          "https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
        ],
        "signing_options": {
          "draw": true,
          "type": true,
          "upload": true,
          "phone": false,
          "default_type": "draw"
        },
        "test_mode": true
      }
      ```
    </CodeBlock>
  </Tab>

  <Tab title="Code">
    <EndpointRequestSnippet endpoint="POST signature_request/create_embedded" example="grouped_signers_example" />

    {/* <CodeBlock>
    ```bash cURL
      curl -X POST 'https://api.hellosign.com/v3/signature_request/create_embedded' \
      -u 'YOUR_API_KEY:' \
      -F 'client_id=YOUR_CLIENT_ID' \
      -F 'files[0]=@mutual-NDA-example.pdf' \
      -F 'title=NDA with Acme Co.' \
      -F 'subject=The NDA we talked about' \
      -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
      -F 'signers[0][email_address]=jack@example.com' \
      -F 'signers[0][name]=Jack' \
      -F 'signers[0][order]=0' \
      -F 'signers[1][email_address]=jill@example.com' \
      -F 'signers[1][name]=Jill' \
      -F 'signers[1][order]=1' \
      -F 'cc_email_addresses[]=lawyer1@dropboxsign.com' \
      -F 'cc_email_addresses[]=lawyer2@dropboxsign.com' \
      -F 'signing_options[draw]=1' \
      -F 'signing_options[type]=1' \
      -F 'signing_options[upload]=1' \
      -F 'signing_options[phone]=1' \
      -F 'signing_options[default_type]=draw' \
      -F 'test_mode=1'
      ```

      ```php PHP
      <?php

      namespace Dropbox\SignSandbox;

      require_once __DIR__ . '/../vendor/autoload.php';

      use SplFileObject;
      use Dropbox;

      $config = Dropbox\Sign\Configuration::getDefaultConfiguration();
      $config->setUsername("YOUR_API_KEY");
      // $config->setAccessToken("YOUR_ACCESS_TOKEN");

      $signing_options = (new Dropbox\Sign\Model\SubSigningOptions())
          ->setDefaultType(Dropbox\Sign\Model\SubSigningOptions::DEFAULT_TYPE_DRAW)
          ->setDraw(true)
          ->setPhone(false)
          ->setType(true)
          ->setUpload(true);

      $signers_1 = (new Dropbox\Sign\Model\SubSignatureRequestSigner())
          ->setName("Jack")
          ->setEmailAddress("jack@example.com")
          ->setOrder(0);

      $signers_2 = (new Dropbox\Sign\Model\SubSignatureRequestSigner())
          ->setName("Jill")
          ->setEmailAddress("jill@example.com")
          ->setOrder(1);

      $signers = [
          $signers_1,
          $signers_2,
      ];

      $signature_request_create_embedded_request = (new Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest())
          ->setClientId("b6b8e7deaf8f0b95c029dca049356d4a2cf9710a")
          ->setMessage("Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.")
          ->setSubject("The NDA we talked about")
          ->setTestMode(true)
          ->setTitle("NDA with Acme Co.")
          ->setCcEmailAddresses([
              "lawyer1@dropboxsign.com",
              "lawyer2@dropboxsign.com",
          ])
          ->setFiles([
          ])
          ->setSigningOptions($signing_options)
          ->setSigners($signers);

      try {
          $response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->signatureRequestCreateEmbedded(
              signature_request_create_embedded_request: $signature_request_create_embedded_request,
          );

          print_r($response);
      } catch (Dropbox\Sign\ApiException $e) {
          echo "Exception when calling SignatureRequestApi#signatureRequestCreateEmbedded: {$e->getMessage()}";
      }

      ```
      
      ```csharp C#
      using System;
      using System.Collections.Generic;
      using System.IO;
      using System.Text.Json;

      using Dropbox.Sign.Api;
      using Dropbox.Sign.Client;
      using Dropbox.Sign.Model;

      namespace Dropbox.SignSandbox;

      public class SignatureRequestCreateEmbeddedExample
      {
          public static void Run()
          {
              var config = new Configuration();
              config.Username = "YOUR_API_KEY";
              // config.AccessToken = "YOUR_ACCESS_TOKEN";

              var signingOptions = new SubSigningOptions(
                  defaultType: SubSigningOptions.DefaultTypeEnum.Draw,
                  draw: true,
                  phone: false,
                  type: true,
                  upload: true
              );

              var signers1 = new SubSignatureRequestSigner(
                  name: "Jack",
                  emailAddress: "jack@example.com",
                  order: 0
              );

              var signers2 = new SubSignatureRequestSigner(
                  name: "Jill",
                  emailAddress: "jill@example.com",
                  order: 1
              );

              var signers = new List<SubSignatureRequestSigner>
              {
                  signers1,
                  signers2,
              };

              var signatureRequestCreateEmbeddedRequest = new SignatureRequestCreateEmbeddedRequest(
                  clientId: "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
                  message: "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
                  subject: "The NDA we talked about",
                  testMode: true,
                  title: "NDA with Acme Co.",
                  ccEmailAddresses: [
                      "lawyer1@dropboxsign.com",
                      "lawyer2@dropboxsign.com",
                  ],
                  files: new List<Stream>
                  {
                      new FileStream(
                          path: "./example_signature_request.pdf",
                          mode: FileMode.Open
                      ),
                  },
                  signingOptions: signingOptions,
                  signers: signers
              );

              try
              {
                  var response = new SignatureRequestApi(config).SignatureRequestCreateEmbedded(
                      signatureRequestCreateEmbeddedRequest: signatureRequestCreateEmbeddedRequest
                  );

                  Console.WriteLine(response);
              }
              catch (ApiException e)
              {
                  Console.WriteLine("Exception when calling SignatureRequestApi#SignatureRequestCreateEmbedded: " + e.Message);
                  Console.WriteLine("Status Code: " + e.ErrorCode);
                  Console.WriteLine(e.StackTrace);
              }
          }
      }
      ```
      
      ```ts TypeScript
      import * as fs from 'fs';
      import api from "@dropbox/sign"
      import models from "@dropbox/sign"

      const apiCaller = new api.SignatureRequestApi();
      apiCaller.username = "YOUR_API_KEY";
      // apiCaller.accessToken = "YOUR_ACCESS_TOKEN";

      const signingOptions: models.SubSigningOptions = {
        defaultType: models.SubSigningOptions.DefaultTypeEnum.Draw,
        draw: true,
        phone: false,
        type: true,
        upload: true,
      };

      const signers1: models.SubSignatureRequestSigner = {
        name: "Jack",
        emailAddress: "jack@example.com",
        order: 0,
      };

      const signers2: models.SubSignatureRequestSigner = {
        name: "Jill",
        emailAddress: "jill@example.com",
        order: 1,
      };

      const signers = [
        signers1,
        signers2,
      ];

      const signatureRequestCreateEmbeddedRequest: models.SignatureRequestCreateEmbeddedRequest = {
        clientId: "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
        message: "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
        subject: "The NDA we talked about",
        testMode: true,
        title: "NDA with Acme Co.",
        ccEmailAddresses: [
          "lawyer1@dropboxsign.com",
          "lawyer2@dropboxsign.com",
        ],
        files: [
          fs.createReadStream("./example_signature_request.pdf"),
        ],
        signingOptions: signingOptions,
        signers: signers,
      };

      apiCaller.signatureRequestCreateEmbedded(
        signatureRequestCreateEmbeddedRequest,
      ).then(response => {
        console.log(response.body);
      }).catch(error => {
        console.log("Exception when calling SignatureRequestApi#signatureRequestCreateEmbedded:");
        console.log(error.body);
      });

      ```
      
      ```java Java
      package com.dropbox.sign_sandbox;

      import com.dropbox.sign.ApiException;
      import com.dropbox.sign.Configuration;
      import com.dropbox.sign.api.*;
      import com.dropbox.sign.auth.*;
      import com.dropbox.sign.JSON;
      import com.dropbox.sign.model.*;

      import java.io.File;
      import java.math.BigDecimal;
      import java.time.LocalDate;
      import java.time.OffsetDateTime;
      import java.util.ArrayList;
      import java.util.List;
      import java.util.Map;

      public class SignatureRequestCreateEmbeddedExample
      {
          public static void main(String[] args)
          {
              var config = Configuration.getDefaultApiClient();
              ((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
              // ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");

              var signingOptions = new SubSigningOptions();
              signingOptions.defaultType(SubSigningOptions.DefaultTypeEnum.DRAW);
              signingOptions.draw(true);
              signingOptions.phone(false);
              signingOptions.type(true);
              signingOptions.upload(true);

              var signers1 = new SubSignatureRequestSigner();
              signers1.name("Jack");
              signers1.emailAddress("jack@example.com");
              signers1.order(0);

              var signers2 = new SubSignatureRequestSigner();
              signers2.name("Jill");
              signers2.emailAddress("jill@example.com");
              signers2.order(1);

              var signers = new ArrayList<SubSignatureRequestSigner>(List.of (
                  signers1,
                  signers2
              ));

              var signatureRequestCreateEmbeddedRequest = new SignatureRequestCreateEmbeddedRequest();
              signatureRequestCreateEmbeddedRequest.clientId("b6b8e7deaf8f0b95c029dca049356d4a2cf9710a");
              signatureRequestCreateEmbeddedRequest.message("Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.");
              signatureRequestCreateEmbeddedRequest.subject("The NDA we talked about");
              signatureRequestCreateEmbeddedRequest.testMode(true);
              signatureRequestCreateEmbeddedRequest.title("NDA with Acme Co.");
              signatureRequestCreateEmbeddedRequest.ccEmailAddresses(List.of (
                  "lawyer1@dropboxsign.com",
                  "lawyer2@dropboxsign.com"
              ));
              signatureRequestCreateEmbeddedRequest.files(List.of (
                  new File("./example_signature_request.pdf")
              ));
              signatureRequestCreateEmbeddedRequest.signingOptions(signingOptions);
              signatureRequestCreateEmbeddedRequest.signers(signers);

              try
              {
                  var response = new SignatureRequestApi(config).signatureRequestCreateEmbedded(
                      signatureRequestCreateEmbeddedRequest
                  );

                  System.out.println(response);
              } catch (ApiException e) {
                  System.err.println("Exception when calling SignatureRequestApi#signatureRequestCreateEmbedded");
                  System.err.println("Status code: " + e.getCode());
                  System.err.println("Reason: " + e.getResponseBody());
                  System.err.println("Response headers: " + e.getResponseHeaders());
                  e.printStackTrace();
              }
          }
      }
      ```
      
      ```ruby Ruby
      require "json"
      require "dropbox-sign"

      Dropbox::Sign.configure do |config|
          config.username = "YOUR_API_KEY"
          # config.access_token = "YOUR_ACCESS_TOKEN"
      end

      signing_options = Dropbox::Sign::SubSigningOptions.new
      signing_options.default_type = "draw"
      signing_options.draw = true
      signing_options.phone = false
      signing_options.type = true
      signing_options.upload = true

      signers_1 = Dropbox::Sign::SubSignatureRequestSigner.new
      signers_1.name = "Jack"
      signers_1.email_address = "jack@example.com"
      signers_1.order = 0

      signers_2 = Dropbox::Sign::SubSignatureRequestSigner.new
      signers_2.name = "Jill"
      signers_2.email_address = "jill@example.com"
      signers_2.order = 1

      signers = [
          signers_1,
          signers_2,
      ]

      signature_request_create_embedded_request = Dropbox::Sign::SignatureRequestCreateEmbeddedRequest.new
      signature_request_create_embedded_request.client_id = "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a"
      signature_request_create_embedded_request.message = "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions."
      signature_request_create_embedded_request.subject = "The NDA we talked about"
      signature_request_create_embedded_request.test_mode = true
      signature_request_create_embedded_request.title = "NDA with Acme Co."
      signature_request_create_embedded_request.cc_email_addresses = [
          "lawyer1@dropboxsign.com",
          "lawyer2@dropboxsign.com",
      ]
      signature_request_create_embedded_request.files = [
          File.new("./example_signature_request.pdf", "r"),
      ]
      signature_request_create_embedded_request.signing_options = signing_options
      signature_request_create_embedded_request.signers = signers

      begin
          response = Dropbox::Sign::SignatureRequestApi.new.signature_request_create_embedded(
              signature_request_create_embedded_request,
          )

          p response
      rescue Dropbox::Sign::ApiError => e
          puts "Exception when calling SignatureRequestApi#signature_request_create_embedded: #{e}"
      end

      ```
      
      ```python Python
      import json
      from datetime import date, datetime
      from pprint import pprint

      from dropbox_sign import ApiClient, ApiException, Configuration, api, models

      configuration = Configuration(
          username="YOUR_API_KEY",
          # access_token="YOUR_ACCESS_TOKEN",
      )

      with ApiClient(configuration) as api_client:
          signing_options = models.SubSigningOptions(
              default_type="draw",
              draw=True,
              phone=False,
              type=True,
              upload=True,
          )

          signers_1 = models.SubSignatureRequestSigner(
              name="Jack",
              email_address="jack@example.com",
              order=0,
          )

          signers_2 = models.SubSignatureRequestSigner(
              name="Jill",
              email_address="jill@example.com",
              order=1,
          )

          signers = [
              signers_1,
              signers_2,
          ]

          signature_request_create_embedded_request = models.SignatureRequestCreateEmbeddedRequest(
              client_id="b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
              message="Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
              subject="The NDA we talked about",
              test_mode=True,
              title="NDA with Acme Co.",
              cc_email_addresses=[
                  "lawyer1@dropboxsign.com",
                  "lawyer2@dropboxsign.com",
              ],
              files=[
                  open("./example_signature_request.pdf", "rb").read(),
              ],
              signing_options=signing_options,
              signers=signers,
          )

          try:
              response = api.SignatureRequestApi(api_client).signature_request_create_embedded(
                  signature_request_create_embedded_request=signature_request_create_embedded_request,
              )

              pprint(response)
          except ApiException as e:
              print("Exception when calling SignatureRequestApi#signature_request_create_embedded: %s\n" % e)

      ```
      
      </CodeBlock> */}
  </Tab>
</Tabs>

You just created an embedded signature request with two signers (Jack and Jill). In the response object, you will notice both signers have been assigned a unique `signature_id`. When one of these users visits your site, you will need to use the Dropbox Sign API generate a temporary `sign_url` using the signer's unique signature ID.

<Warning title="Important">
  In order to generate a `sign_url` the **unique** `signature_id` (per signer) will be needed and **not** the `signature_request_id`.
</Warning>

### Generating a `sign_url`

Endpoint: [/embedded/sign\_url/\{signature\_id}](/api/embedded/sign-url)

<EndpointRequestSnippet endpoint="GET /embedded/sign_url/{signature_id}" />

{/* <CodeBlock>
```bash cURL
curl -X GET 'https://api.hellosign.com/v3/embedded/sign_url/{signature_id}' \
  -u 'YOUR_API_KEY:'
```

```php PHP
<?php

namespace Dropbox\SignSandbox;

require_once __DIR__ . '/../vendor/autoload.php';

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

try {
    $response = (new Dropbox\Sign\Api\EmbeddedApi(config: $config))->embeddedSignUrl(
        signature_id: "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b",
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling EmbeddedApi#embeddedSignUrl: {$e->getMessage()}";
}

```

```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;

using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;

namespace Dropbox.SignSandbox;

public class EmbeddedSignUrlExample
{
    public static void Run()
    {
        var config = new Configuration();
        config.Username = "YOUR_API_KEY";
        // config.AccessToken = "YOUR_ACCESS_TOKEN";

        try
        {
            var response = new EmbeddedApi(config).EmbeddedSignUrl(
                signatureId: "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b"
            );

            Console.WriteLine(response);
        }
        catch (ApiException e)
        {
            Console.WriteLine("Exception when calling EmbeddedApi#EmbeddedSignUrl: " + e.Message);
            Console.WriteLine("Status Code: " + e.ErrorCode);
            Console.WriteLine(e.StackTrace);
        }
    }
}

```

```ts TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"

const apiCaller = new api.EmbeddedApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";

apiCaller.embeddedSignUrl(
  "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b", // signatureId
).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log("Exception when calling EmbeddedApi#embeddedSignUrl:");
  console.log(error.body);
});
```
```java Java
package com.dropbox.sign_sandbox;

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;

import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class EmbeddedSignUrlExample
{
    public static void main(String[] args)
    {
        var config = Configuration.getDefaultApiClient();
        ((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
        // ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");

        try
        {
            var response = new EmbeddedApi(config).embeddedSignUrl(
                "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b" // signatureId
            );

            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling EmbeddedApi#embeddedSignUrl");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}
```
```ruby Ruby
require "json"
require "dropbox-sign"

Dropbox::Sign.configure do |config|
    config.username = "YOUR_API_KEY"
    # config.access_token = "YOUR_ACCESS_TOKEN"
end

begin
    response = Dropbox::Sign::EmbeddedApi.new.embedded_sign_url(
        "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b", # signature_id
    )

    p response
rescue Dropbox::Sign::ApiError => e
    puts "Exception when calling EmbeddedApi#embedded_sign_url: #{e}"
end
```
```python Python
import json
from datetime import date, datetime
from pprint import pprint

from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(
    username="YOUR_API_KEY",
    # access_token="YOUR_ACCESS_TOKEN",
)

with ApiClient(configuration) as api_client:
    try:
        response = api.EmbeddedApi(api_client).embedded_sign_url(
            signature_id="50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b",
        )

        pprint(response)
    except ApiException as e:
        print("Exception when calling EmbeddedApi#embedded_sign_url: %s\n" % e)
```

</CodeBlock> */}

<Warning title="Important">
  This call will return HTTP `409` if the signature request has already been signed by this signer or—in the case of ordered signing—the request cannot be signed yet because it's not their turn. A successful response will return an object which contains a `sign_url` property. The `sign_url` is used to load the iFrame on your site using the [hellosign-embedded](https://github.com/hellosign/hellosign-embedded).
</Warning>

## Client Side

We provide a client-side library that handles the authorization and display of the embedded request using an iFrame. You can use this feature by adding a few lines of JavaScript code.

If you are using a modern module bundler with [npm](https://npmjs.com/package/hellosign-embedded), simply install `hellosign-embedded`.

```bash
npm install hellosign-embedded
```

If you are not using a modern module bundler like npm, our library can be [downloaded manually](https://github.com/hellosign/hellosign-embedded/releases), [compiled from source](https://github.com/hellosign/hellosign-embedded/wiki/Compile-From-Source), or [imported from our CDN](https://github.com/hellosign/hellosign-embedded/wiki/CDN-Links).

In your app, import the `hellosign-embedded` module, instantiate a new client, then invoke `open()` with your `sign_url` and API client ID. Note that we're using `skipDomainVerification` when calling this method. You can learn more about that in the [Domain Restriction](#domain-restriction) section below.

```bash
import HelloSign from 'hellosign-embedded';

const client = new HelloSign();

client.open(claimUrl, {
  clientId: 'Your API client ID',
  skipDomainVerification: true
});
```

<Note title="Note" icon="fa-light fa-triangle-exclamation">
  It's recommended that you add the following to your document's `<head>` to avoid unexpected behavior on small screens. `<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">`
</Note>

There are a number of options you can define as part of the second argument when calling `open()`:

<table>
  <thead>
    <tr>
      <th width="20%">
        Name
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>requestingEmail</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        The email of the account issuing the signature request.<br /><br />
        **Note:** This option is only necessary for **'Me and Others'** type signature requests.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  requestingEmail: "[alice@example.com](mailto:alice@example.com)"<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>locale</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        The locale code that will be used to determine which language the embedded request will be displayed in. For a list of Dropbox Sign's supported languages, visit our <a href="https://help.dropbox.com/integrations/force-foreign-language-on-signer-page">Languages page</a>. If no locale is specified Dropbox Sign will attempt to determine the user's preferred language by their browser settings or fall back to English.<br /><br />
        **Note:** Czech (`CS_CZ`) is only supported by Embedded Signing.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  locale: HelloSign.locales.ZH_CN<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>redirectTo</code>
      </td>

      <td>
        <code>string</code>
      </td>

      <td>
        Where the user will be redirected after sending the signature request.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  redirectTo: "[http://example.com](http://example.com)"<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>allowCancel</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        Whether the user should be able to close the iFrame without finishing the request. **Default:** `true`.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  allowCancel: false<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>debug</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        Allows debug output to print to the console. **Default:** `false`.<br /><br />
        For even more detailed debug output, run `localStorage.debug = 'hellosign-embedded:*';` in your developer console and refresh the page.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  debug: true<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>skipDomainVerification</code>
      </td>

      <td>
        <code>boolean</code>
      </td>

      <td>
        Whether or not to skip the domain verification step. **Default:** `false`.<br /><br />
        **Note:** This will only be honored if the signature request was created with `test_mode=1`.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  skipDomainVerification: true<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>timeout</code>
      </td>

      <td>
        <code>number</code>
      </td>

      <td>
        How long (in milliseconds) to wait for the app to initialize before aborting. **Default:** `30000` (30 seconds).<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  timeout: 10000<br />{'}'}</code>
        </pre>
      </td>
    </tr>

    <tr>
      <td>
        <code>container</code>
      </td>

      <td>
        <code>HTMLElement</code>
      </td>

      <td>
        By default a modal will be opened, but by specifying `container` you can choose a DOM element on the page in which the iFrame will be embedded.<br /><br />
        **Example:**

        <br />

        <pre>
          <code>{'{'}<br />  container: document.getElementById('sign-here')<br />{'}'}</code>
        </pre>
      </td>
    </tr>
  </tbody>
</table>

## Additional notes

### App Approval

In order to ensure that integrations adhere to eSignature regulations and best practices, an app approval is needed prior to moving into production for all customers implementing embedded signing, embedded requesting, embedded templates, and OAuth workflows.

<Warning title="Important" icon="fa-light fa-circle-exclamation">
  You will still be able to use your app in test mode until it gets approved. Only live/production activity requires approval.
</Warning>

Please refer to the [App Approval Section](/docs/guides/app-approval/overview) for more detailed information about getting your app approved.

### Domain Restriction

When the iFrame is loaded, it will verify the domain of the parent window and ensure it matches the domain name of the API app specified by the client ID. If the domain does not match, the page won't be loaded.

You can disable domain restriction for easier development:

```bash
client.open(signUrl, {
  // ...
  skipDomainVerification: true
});
```

This will allow you to use development domains, like `localhost`. See the documentation for `open()` method in the section above.

### HTTPS Required

The host page must be served over HTTPS. The iFrame is also loaded over HTTPS, and due to browser security restrictions it will not be able to communicate with the parent window if it is not HTTPS. This communication is required to enable features such as iFrame callbacks and closing the iFrame.

To make development easier, the page will still load if the parent window is served over HTTP, however an alert will be displayed to notify you of this requirement. Switch to HTTPS to prevent this alert from being displayed.

### Redirection

If a redirect url is specified, the iFrame will redirect users to it after they send the document(s). Data from the `sign` event will be appended to the url query string.

### Signature Links

Signature URLs are only valid for 60 minutes after [/embedded/sign\_url](/api/embedded/sign-url) has been called and expire as soon as they're accessed.

It is best practice to wait until your signer hits the page before generating the `sign_url` so the link doesn't expire before the signer is ready. However, since the `signature_id` itself does not expire, a fresh `sign_url` can always be generated.

### Text Tags

The embedded functionality can be used in conjunction with Dropbox Sign [Text Tags](/docs/walkthroughs/text-tags).

### Client Side Events

There are a number of events that the client may emit. To listen to these events, pass the event name and a callback function to `on()`. An string enumeration of available events can also be found under `HelloSign.events`.

```bash
client.on('sign', (data) => {
  console.log('The document has been signed!');
  console.log('Signature ID: ' + data.signatureId);
});
```

Here are a list of possible events:

| Event            | Description                                                                                                                                     | Data                                                                                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createTemplate` | Emitted when the user creates the signature request template.                                                                                   | <pre><code>{'{'}<br />  templateId,<br />  templateInfo {'{'}<br />    title,<br />    message,<br />    signerRoles,<br />    ccRoles<br />  {'}'}<br />{'}'}</code></pre> |
| `open`           | Emitted when the embedded window has opened.                                                                                                    | <pre><code>{'{'}<br />  url,<br />  iFrameUrl<br />{'}'}</code></pre>                                                                                                       |
| `cancel`         | Emitted when the template was canceled by the user by either pressing the close button or selecting "close" from the dropdown list.             |                                                                                                                                                                             |
| `finish`         | Emitted when the user has finished the embedded template flow without cancelling.                                                               |                                                                                                                                                                             |
| `message`        | Emitted when embedded has received a [cross-origin window message](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent) from the app. | <pre><code>{'{'}<br />  type,<br />  payload<br />{'}'}</code></pre>                                                                                                        |
| `close`          | Emitted when the embedded window has closed.                                                                                                    |                                                                                                                                                                             |
| `error`          | Emitted when the app encounters an error.                                                                                                       | <pre><code>{'{'}<br />  signatureId,<br />  code<br />{'}'}</code></pre>                                                                                                    |