Embedded Signature Requests

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.

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

2. Notify the User

Create Signature Request Event API API documentation for creating signature request events

DocSpring does not currently send emails on your behalf, 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.

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:

2024-01-01 12:00:00 - Reported by Acme Inc via API: sent a signing link by email to [email protected], at 2024-01-01 11:59:30 UTC
2024-01-01 12:10:00 - Viewed by Test ([email protected])
2024-01-01 12:20:00 - Signed by Test ([email protected])
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 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 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:

<script
  type="text/javascript"
  src="https://cdn.docspring.com/embed/signature_request.v3.0.0.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'.

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. If your page is itself shown in a frame on another site, list that site too: the browser checks every page around the form. Pages that still load Data Requests JS 2.x also check the list themselves, and only match a listed host exactly (no wildcards or schemes).

View Complete Example Interactive example with all available options

Web Forms + Signature Requests

Using Web Forms and Signature Requests Together 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:

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

Next Steps

Signature Requests JavaScript API Reference Complete reference for DocSpring.createSignatureRequestForm() options and callbacks

Signature Requests Documentation Learn about signature requests and how they work

Signature Requests JS Changelog Changelog entries for the Signature Requests JavaScript library