***
description: Embedded signature requesting allows users to create, edit, and send signature requests on your site. Read the setup steps here.
og:description: Embedded signature requesting allows users to create, edit, and send signature requests on your site. Read the setup steps here.
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://developers.hellosign.com/docs/walkthroughs/llms.txt. For full documentation content, see https://developers.hellosign.com/docs/walkthroughs/llms-full.txt.
# Embedded Requesting Walkthrough
Embedded Requesting allows you to have users create and send signature requests on your site in an iFrame using [hellosign-embedded](https://github.com/hellosign/hellosign-embedded), Dropbox Sign's official client-side library. The documentation below describes requirements and setup steps for the embedded requesting flow.
## Preliminary
Please complete the steps below before following along with the content.
1. [Create an API app](https://app.hellosign.com/oauth/createAppForm) (login required)
The API app domain name specifies where the iFrame can be opened. Embedded Requesting will only be possible on pages from this domain and its subdomains. However, you can use `skipDomainVerification` to embed requests created using `test_mode`.
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 Dropbox Sign Embedded 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 `edit_url` that you'll generate in the [Server Side](#server-side) section below.
## Server Side
The very first step is to create a "draft" signature request from the backend using our API. You must decide what you want to happen after the signature request is sent by your user. By default, Dropbox Sign will send an email to the signers and ask them to come to hellosign.com to sign and complete the document(s):
```json title="Default Example"
{
"client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
"file_urls": [
"https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
],
"requester_email_address": "jack@dropboxsign.com",
"test_mode": true
}
```
```json title="Form Fields Per Document Example"
{
"client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
"file_urls": [
"https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
],
"form_fields_per_document": [
{
"document_index": 0,
"api_id": "uniqueIdHere_1",
"name": "",
"placeholder": "",
"type": "text",
"x": 112,
"y": 328,
"width": 100,
"height": 16,
"required": true,
"signer": 1,
"page": 1,
"validation_type": "numbers_only"
},
{
"document_index": 0,
"api_id": "uniqueIdHere_2",
"name": "",
"type": "signature",
"x": 530,
"y": 415,
"width": 120,
"height": 30,
"required": true,
"signer": 0,
"page": 1
}
],
"requester_email_address": "jack@dropboxsign.com",
"test_mode": false
}
```
```json title="Form Fields Per Document and Groups Example"
{
"client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
"file_urls": [
"https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
],
"form_fields_per_document": [
{
"document_index": 0,
"api_id": "uniqueIdHere_1",
"name": "",
"type": "radio",
"x": 112,
"y": 328,
"width": 18,
"height": 18,
"required": false,
"group": "RadioItemGroup1",
"is_checked": 1,
"signer": 0,
"page": 1
},
{
"document_index": 0,
"api_id": "uniqueIdHere_2",
"name": "",
"type": "radio",
"x": 112,
"y": 370,
"width": 18,
"height": 18,
"required": false,
"group": "RadioItemGroup1",
"is_checked": 0,
"signer": 0,
"page": 1
}
],
"form_field_groups": [
{
"group_id": "RadioItemGroup1",
"group_label": "Radio Item Group 1",
"requirement": "require_0-1"
}
],
"requester_email_address": "jack@dropboxsign.com",
"test_mode": false
}
```
```json title="Form Fields Per Document and Rules Example"
{
"client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
"file_urls": [
"https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
],
"form_fields_per_document": [
{
"document_index": 0,
"api_id": "uniqueIdHere_1",
"name": "",
"type": "text",
"x": 112,
"y": 328,
"width": 100,
"height": 16,
"required": true,
"signer": 0,
"page": 1,
"validation_type": "numbers_only"
},
{
"document_index": 0,
"api_id": "uniqueIdHere_2",
"name": "",
"type": "signature",
"x": 530,
"y": 415,
"width": 120,
"height": 30,
"required": true,
"signer": 0,
"page": 1
}
],
"form_field_rules": [
{
"id": "rule_1",
"trigger_operator": "AND",
"triggers": [
{
"id": "uniqueIdHere_1",
"operator": "is",
"value": "foo"
}
],
"actions": [
{
"field_id": "uniqueIdHere_2",
"hidden": 1,
"type": "change-field-visibility"
}
]
}
],
"requester_email_address": "jack@dropboxsign.com",
"test_mode": false
}
```
Alternatively, you can use embedded requesting in conjunction with [embedded signing](/docs/walkthroughs/embedded-signing) by specifying the `is_for_embedded_signing` parameter. This will instruct Dropbox Sign to NOT email the signers and will allow you to decide when and how to display the embedded signing iFrame on your site.
In the aforementioned scenario, you will need to retrieve the signature url after the request has been sent using [/embedded/sign\_url](/api/embedded/sign-url). See the [embedded signing walkthrough](/docs/walkthroughs/embedded-signing) to learn how to construct the embedded signing page from that point on.
If you'd like to specify the signers and CCs during this step (rather than let the user specify them when they edit and send the signature request), you can include the `signers` and `cc_email_addresses` parameters. See the [/unclaimed\_draft/create\_embedded](/api/unclaimed-draft/create-embedded) documentation for more info.
In this section, you created an Embedded Signature Request for [jack@dropbox.com](mailto:jack@dropbox.com). When Jack accesses the embedded request, she'll make edits to the signature request and send it out once complete. You'll need to grab the `claim_url` from the JSON response. The `claim_url` is passed to the [Client Side](#client-side) to use in Dropbox Sign Embedded's `open()` method.
## 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 bunder 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 `claimUrl` 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,
});
```
It's recommended that you add the following to your document's `` to avoid unexpected behavior on small screens. ``
There are a number of options you can define as part of the second argument when calling `open()`:
| Name | Type | Description |
| ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestingEmail` | `string` | The email of the account issuing the signature request.
**Note:** This option is only necessary for **'Me and Others'** type signature requests.
**Example:**{'{'}
"requestingEmail": "[alice@example.com](mailto:alice@example.com)"
{'}'}
|
| `locale` | `string` | 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 Languages page. 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.
**Note:** Czech (`CS_CZ`) is only supported by Embedded Signing.
**Example:**{'{'}
locale: HelloSign.locales.ZH\_CN
{'}'}
|
| `redirectTo` | `string` | Where the user will be redirected after sending the signature request.
**Example:**{'{'}
redirectTo: '[http://example.com](http://example.com)'
{'}'}
|
| `allowCancel` | `boolean` | Whether the user should be able to close the iFrame without finishing the request. **Default:** `true`.
**Example:**{'{'}
allowCancel: false
{'}'}
|
| `debug` | `boolean` | Allows debug output to print to the console. **Default:** `false`.
For even more detailed debug output, run `localStorage.debug = 'hellosign-embedded:*';` in your developer console and refresh the page.
**Example:**{'{'}
debug: true
{'}'}
|
| `skipDomainVerification` | `boolean` | Whether or not to skip the domain verification step. **Default:** `false`.
**Note:** This will only be honored if the signature request was created with `test_mode=1`.
**Example:**{'{'}
skipDomainVerification: true
{'}'}
|
| `timeout` | `number` | How long (in milliseconds) to wait for the app to initialize before aborting. **Default:** `30000` (30 seconds).
**Example:**{'{'}
timeout: 10000
{'}'}
|
| `container` | `HTMLElement` | 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.
**Example:**{'{'}
container: document.getElementById('sign-here')
{'}'}
|
## 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.
You will still be able to use your app in test mode until it gets approved. Only live/production activity requires approval.
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 `send` event will be appended to the url query string.
### 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 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send` | Emitted when the user sends the signature request. | {'{'}
signatureRequestId,
signatureRequestInfo {'{'}
title,
message,
signatures,
ccEmailAddresses
{'}'}
{'}'}
|
| `open` | Emitted when the embedded window has opened. | {'{'}
url,
iFrameUrl
{'}'}
|
| `cancel` | Emitted when the signature request 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 signature request flow without cancelling. However, the user may have declined or reassigned the signature request. | |
| `message` | Emitted when embedded has received a [cross-origin window message](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent) from the app. | {'{'}
type,
payload
{'}'}
|
| `close` | Emitted when the window has closed. | |
| `error` | Emitted when the app encounters an error. | {'{'}
signatureId,
code
{'}'}
|