# Embedded Signature Requests

> Step-by-step guide to implement UETA and ESIGN compliant electronic signatures

Source: https://docspring.com/docs/guides/embedded-forms/embedded-signature-requests/
All of DocSpring's documentation: https://docspring.com/docs/llms.txt

This guide walks through implementing signature requests for collecting legally binding electronic signatures. For conceptual documentation about how signature requests work, see the [Signature Requests documentation](https://docspring.com/docs/forms/signature-requests/).

A test API token can look up a live signature request, but creating its tokens and events and updating its authentication details need a live API token. A test token gets `403 Forbidden` for those.

## Implementation Steps

### 1. Create a Submission with a Signature Request

[Create Signature Requests API Guide](https://docspring.com/docs/api-guide/create-signature-requests/): Learn how to create PDF submissions with pending signature requests

Your signature request will include:

* The user’s full name
* The user’s email address
* The fields that the user must fill out (including signature fields)
* Some optional metadata to save on this signature request
* Details about how and when the user has been authenticated
* `send_email: false`, because your app sends the link. Without it, DocSpring also emails the user a link to sign

> **Tip:** While many authentication fields are optional, provide as much detail as you can. This helps DocSpring build a comprehensive audit trail and ensures electronic signatures will be legally binding if contested in court.

### 2. Notify the User

[Create Signature Request Event API](https://docspring.com/docs/api/#tag/signature-requests/post/signature_requests/{signature_request_id}/events): API documentation for creating signature request events

With `send_email: false`, DocSpring doesn’t email the user, so your server must send an email to your user with a link to the page where they can sign the document. The URL will be a link to your own domain, since you will be embedding the DocSpring JavaScript in a page within your own application. (DocSpring can also send the emails, with links to its own signing page or to a page on your site: see [Emails from DocSpring](https://docspring.com/docs/api-guide/create-signature-requests/#emails-from-docspring).)

Once you have sent the email, inform DocSpring about this event by making an API request to the Create Signature Request Event endpoint, with the `send_request` event type. This event will be shown on the audit trail page once the PDF has been generated, as reported by your account. The endpoint doesn’t accept other event types, and it returns an error once the signature request is completed, declined, or expired.

**Example audit trail log:**

```plaintext
2024-01-01 12:00:00 - Reported by Acme Inc via API: sent a signing link by email to test@example.com, at 2024-01-01 11:59:30 UTC
2024-01-01 12:10:00 - Viewed by Test (test@example.com)
2024-01-01 12:20:00 - Signed by Test (test@example.com)
2024-01-01 12:20:00 - Document completed
```

You will need to track the “sent” event and authentication details yourself. The “viewed”, “signed”, and “completed” events will be automatically recorded by DocSpring when the user interacts with the form.

### 3. Request an Authentication Token

[Create Signature Request Authentication Token API](https://docspring.com/docs/api/#tag/signature-requests/post/signature_requests/{signature_request_id}/tokens): API documentation for creating authentication tokens

Once the user clicks the link and is ready to sign the form, you will need to create an authentication token for your signature request. You should request this token immediately before showing the signing form to the user. Its link opens the form for 24 hours, and a form that opened in time keeps working for 7 more days. When the link has expired, the form says so and Signature Requests JS calls `onError` with the code `token_expired`.

### 4. Update Authentication Details

[Update Signature Request API](https://docspring.com/docs/api/#tag/signature-requests/put/signature_requests/{signature_request_id}): API documentation for updating signature requests

If there is a significant delay between creating the signature request and showing the signing form to the user, ensure that the authentication details are accurate. You can make an API request to update these details if the user has signed in again. (However, you cannot update a signature request if it has already been viewed or completed.)

### 5. Render the Signing Form

After you fetch an authentication token, the response will include an authenticated URL that you can provide to your user. Visiting this URL will take them to a signing form hosted on the docspring.com domain.

To embed the form on your own website, copy the following code into your page:

`Basic signature request embed`

```html
<script
  type="text/javascript"
  src="https://cdn.docspring.com/embed/signature_request.v3.0.2.js"
></script>


<script>
  DocSpring.createSignatureRequestForm({
    signatureRequestId: 'SIGNATURE_REQUEST_ID',
    tokenId: 'TOKEN_ID',
    tokenSecret: 'TOKEN_SECRET',
  })
</script>
```

Use the `id` and `secret` from the token response as `tokenId` and `tokenSecret`. If your account is in the EU region, also pass `region: 'EU'`.

> **Note:** [DocSpring Enterprise](https://docspring.com/docs/enterprise/) deployments can load this script from the local DocSpring domain instead of the CDN: `https://docspring.yourcompany.com/assets/embed/signature_request.js`.

This code will open the form in a modal overlay. You may also pass a CSS selector as the first argument, and the iframe element will be appended to that selector. (However, mobile browsers will always use a full-screen overlay.)

Add your website’s domain to the template’s **Embed Domains** setting, such as `app.example.com`. A live signature request only loads on the sites listed there: the browser refuses to show it anywhere else, and your `onError` callback receives the `frame_blocked` error. You can list a wildcard such as `*.example.com`, a port such as `localhost:3000`, or a scheme such as `https://app.example.com` (a domain without a scheme allows both `http` and `https`). Test signature requests load on any site, so you can develop without listing `localhost`. A path, such as `app.example.com/sign`, is dropped when you save: the browser only checks the scheme, domain and port. If your page is itself shown in a frame on another site, list that site too: the browser checks every page around the form. The same setting limits where the template’s [embedded template editor](https://docspring.com/docs/guides/embedded-template-editor/#embed-domains) and [visual forms](https://docspring.com/docs/guides/embedded-forms/embedded-visual-forms/#embed-domains) load, so list the sites where you embed those too.

[View Complete Example](https://docspring.com/embed_signature_request_example): Interactive example with all available options

> **Tip:** “View Source” in your browser to see how the JavaScript library is used in the example above.

> **Note:** From version 2.4.0, the signing form includes a **Decline** button in the header, so a signer can decline at any time. If a signer declines, the whole submission is cancelled and no PDF is generated. Hide the button with `showDecline: false`, rename it with the `declineButtonLabel` option, and handle the event with the `onDecline` callback. See [Declining to Sign](https://docspring.com/docs/forms/signature-requests/#declining-to-sign).

## Web Forms + Signature Requests

[Using Web Forms and Signature Requests Together](https://docspring.com/docs/guides/embedded-forms/web-forms-with-signature-requests/): Use web forms to collect data, then create a signature request to sign the PDF

## Redirect After Submission

After the user submits the form, you can redirect them to a different URL. The redirect URL can be configured in the template settings, or it can be passed as the `redirectURL` option to `DocSpring.createSignatureRequestForm()`, which overrides the template’s redirect URL.

The submission details will be appended to the redirect URL as query parameters:

```plaintext
https://example.com/?submission_id=sub_123&template_id=tpl_123&template_name=My%20Template
```

> **Note:**
>
> * **Private submissions**: Redirects immediately after saving
> * **Public submissions**: Waits for PDF processing before redirecting. If other signature requests still need to be filled in, the PDF isn’t generated yet, so the form redirects one second after calling `onRemainingSignatureRequests`

## Next Steps

[Signature Requests JavaScript API Reference](https://docspring.com/docs/forms/js-libraries/signature-requests-js/): Complete reference for DocSpring.createSignatureRequestForm() options and callbacks

[Signature Requests Documentation](https://docspring.com/docs/forms/signature-requests/): Learn about signature requests and how they work

[Signature Requests JS Changelog](https://docspring.com/docs/changelogs/signature-requests-js/): Changelog entries for the Signature Requests JavaScript library
