Data Requests

Overview

Create a Data Request to collect UETA and ESIGN compliant electronic signatures.

When you make an API request to fill out a PDF, you can specify that some fields must be filled in by certain people (including signature fields.) The PDF submission will be in a pending state until of the data requests have been completed. You can then send these people a link to fill in the form, or embed this form on your own website. When everyone has filled in the form, the PDF will be generated, and we can send your server a webhook notification.

To collect UETA and ESIGN compliant electronic signatures, DocSpring must record an audit trail that includes user authentication. This means that you need to send us some details about how and when your users have been authenticated.

Release Notes

You can find the latest version and release notes here:

• Release Notes for Data Requests JS Library

Steps

Here is an overview of how Data Requests work:

• Make an API request to create a new submission. Include one or more data_requests, with details about the people who will be filling out and signing the document. You must include their full name, email address, the fields they need to complete, and information about how they have been authenticated in your system (username/password, OAuth, 2FA, etc.)
• DocSpring returns an array of data_requests with an ID for each request.
• Send your user an email with a link to the page where they can sign the form.
  • Make an API request to add a "sent via email" event to the document's audit trail history. This event will be shown on the audit trail page that is appended to the PDF.
• When your user visits the signing link, make an API request to retrieve an authentication token.
  • If you are sending the user an email with a link, the token response will include a formatted URL that you can use.
  • If you are embedding the signing form on your own website, you can call DocSpring.createVisualForm() with the data request ID, the token ID, and the token secret.
• The user visits the signing form, completes all of the required fields, and submits the form.
• If this is the last pending data request, DocSpring generates the final PDF and can send your server a webhook notification.

This process can be quite complex and take some time to implement, but it ensures that DocSpring can record a complete audit trail of events. This ensures that all electronic signatures are legally binding.

Step-By-Step Guide

1) Create a Submission with a Data Request

View the API documentation for: Create Data Request

Your data request will include the following details:

• 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 data request
• Details about how and when the user has been authenticated.

While many of these authentication fields are optional, please provide as much detail as you can. This helps DocSpring to build a comprehensive audit trail, and ensures that the electronic signatures will be legally binding if they are ever contested in a court of law.

2) Notify the user that they need to sign the document

View the API documentation for: Create Data Request Event

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, you can inform DocSpring about this event by making an API request to the Create Data Request Event endpoint. This event will be shown on the audit trail page once the PDF has been generated.

Here is an example audit trail log:

• 2024-01-01 12:00:00 - Sent via email to Test ([email protected])
• 2024-01-01 12:10:00 - Test ([email protected]) signed in via username/password
• 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 via email" event and authenticiation details yourself. The "viewed" and "signed" events will be automatically recorded by DocSpring when the user interacts with the form.

3) Request an authentication token for your Data Request

View the API documentation for: Create Data Request Authentication Token

Once the user clicks the link and is ready to sign the form, you will need to create a one-time authentication token for your data request. This authentication token can only be used once. You should request this token immediately before showing the signing form to the user.

4) Ensure that the authentication details are up to date

View the API documentation for: Update Data Request

If there is a significant delay between creating the Data Request and showing the signing form to the user, then please 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 Data Request if it has already been viewed or completed.) For example, you can let us know if the user has signed in to your application via username and password.

5) Render the signing form on your own website

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.

If you would like to embed the form on your own website, then copy the following code into your page, replacing DATA_REQUEST_ID, TOKEN_ID, and TOKEN_SECRET:

<script
  type="text/javascript"
  src="https://cdn.docspring.com/embed/data_request.v2.3.4.js"
></script>

<script>
  DocSpring.createVisualForm({
    dataRequestId: 'DATA_REQUEST_ID',
    tokenId: 'TOKEN_ID',
    tokenSecret: 'TOKEN_SECRET',
  })
</script>

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 alway use a full-screen overlay.)

We have prepared a more complex example that demonstrates all of the available options for DocSpring.createVisualForm():

• View HTML source
• See the form

You can fill out this form to generate a new Data Request, and then we will show the signing form in a modal overlay.

Simple Forms + Data Requests

The following example shows how you could use a simple form to gather information with text inputs. Then you can create a data request that is prefilled with the data from the simple form. The data request will show a preview of the PDF with the filled-in data before asking the user to sign the form.

• View HTML source
• See the form

In this example, we use the simple embedded forms to show a form, but we hide the signature field in the processTemplateSchema callback by removing it from the template schema. We also cancel the PDF submission by returning false in the onSubmit callback. When the simple form is submitted, we send the data to our server, which makes an API call to create a prefilled data request. (You must also create the data request in your backend code, because you must never include your DocSpring API token in your front-end code.)

For the initial data collection step, you could use any form library that supports JSON schemas, such as react-jsonschema-form.

You must always use a data request if you are collecting legally binding electronic signatures. If you only use a simple form with a signature field, the user could be signing a document that they haven't seen. DocSpring will also not be able to store any information about how the user was authenticated, so these signatures will not be legally binding.

Zooming on Mobile

When an embedded form is displayed on a mobile device, it will always be shown in a full-screen modal overlay. The user can zoom in to enlarge the document and fields. You should use the following viewport meta tag in your HTML <head>:

<meta name="viewport" content="width=device-width, initial-scale=1" />

Do not use maximum-scale=1 or user-scalable=no in this viewport meta tag, because this will prevent the user from zooming in.

Redirect to a URL

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 an option to DocSpring.createVisualForm() (The createVisualForm option will override the template's redirect URL.)

The submission ID, template ID, and template name will be appended to this URL as query params:
https://example.com/?submission_id=sub_123&template_id=tpl_123&template_name=My%20Template

When "Submission Privacy" is set to "Private", the user will be redirected as soon as the form has been saved.

When "Submission Privacy" is set to "Public", the user will be redirected after the PDF has finished processing. If you don't need to wait, you can set the waitForPDF option to false when calling DocSpring.createVisualForm().

JavaScript API

DocSpring.createVisualForm(cssSelector, optionsAndCallbacks = {})

Or:

DocSpring.createVisualForm(optionsAndCallbacks = {})

Options

String Options

Customize the titles and messages that are shown in the header.

The following options can be either a plain string, or a function that returns a string.

Callback Options

Actions

You can call the following JavaScript functions to interact with the form. (Note: These are global functions. This means that only one DocSpring form can be displayed on a page.)

Debugging

You can set DocSpring.DEBUG = true to show extra debugging log messages in the developer console. If you are experiencing any problems with your integration, please enable logging and include the console logs in your support request.