Data Requests

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, FormAPI 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.


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.)
  • FormAPI returns an array of data_requests with an ID for each request.
  • Once your user is ready to sign the document, you make an API request to get an authentication token. (This token will expire in 60 minutes.)
    • 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 FormAPI.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, FormAPI generates the final PDF and can send your server a webhook notification.

This process ensures that FormAPI can build a comprehensive audit trail so that your user's 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 FormAPI 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) Get an authentication token for your Data Request

View the API documentation for: Create Data Request Authentication Token

When you are ready to show the form to your user, you must create a one-time authentication token for your data request. This authentication token can only be used once, and will expire in 1 hour.

3) 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. (But you cannot update a Data Request if it has already been viewed or completed.)

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


    dataRequestId: "DATA_REQUEST_ID",
    tokenId: "TOKEN_ID",
    tokenSecret: "TOKEN_SECRET"

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 FormAPI.createVisualForm():

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.

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 FormAPI 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. FormAPI 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 FormAPI.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:

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 FormAPI.createVisualForm().

JavaScript API

FormAPI.createVisualForm(cssSelector, optionsAndCallbacks = {})


FormAPI.createVisualForm(optionsAndCallbacks = {})


Option Description
dataRequestId Your Data Request ID
tokenId Your Token ID
tokenSecret Your Token Secret
domainVerification Set this to false during development to disable domain verification.
redirectURL Redirect to this URL after submitting the form (Overrides the template's redirect URL)
focusFirstFieldOnLoad Automatically focus the first field after the form is loaded. (Default: false)
showSignatureModalOnFocus Automatically open the signature popup when a signature field is focussed. (Default: false)
closeModalOnClickOverlay Allow the user to close the form by clicking on the modal overlay. (Default: true)
showTermsOfServiceLink Show a link to FormAPI's terms of service on the "Accept Terms" screen. (Default: true)
downloadButtonLabel Change the download button label. (Default: "Down;oad PDF")
showPdfProcessingSpinner Show a spinner while the PDF is being processed. (Default: true)

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.

Option Function Arguments Description
waitingForDataRequestsTitle remainingDataRequestsCount (number), template (object) Title when there are still some pending data requests to be filled in.
waitingForDataRequestsMessage remainingDataRequestsCount (number), template (object) Message when there are still some pending data requests to be filled in.
submittingTitle template (object) Title when the data is being submitted.
submittingMessage template (object) Message when the data is being submitted.
pdfProcessingTitle template (object) Title when the PDF is being processed
pdfProcessingMessage template (object) Message when the PDF is being processed
completedTitle template (object), downloadURL (string) Title when the PDF has been processed.
pdfProcessedMessage template (object), downloadURL (string) Message when the PDF has been processed.
completedTitleNoDownload template (object) Title when the data has been saved, but the submission cannot be polled, so there is no download URL. (Used for private templates, or waitForPDF: false)


Callback Parameters Description
onInitialize - Called when the form has been initialized.
onLoad - Called when all form pages have been loaded.
onClearForm - Called after the clear button is pressed and the form is cleared
onFieldFocus { id, name, value } Called when a field gains focus
onFieldBlur { id, name, value } Called when a field loses focus
onFieldChange { id, name, value, previousValue } Called when a field value changes
onShowAcceptTerms - Called when the user clicks "Continue" to show the final "Accept Terms" screen.
onSubmit formData Called when the submit button is pressed. Parameter is an object with all form data.
onSave submissionId Called when the form has been saved. Parameter is an object containing the submission attributes, including id.
onProcessed { submissionId, downloadUrl } Called when the PDF has been processed. (Will only be called if "Submission Privacy" is set to "Public".)
onRemainingDataRequests remainingDataRequestsCount Called when the form data has been saved, but other data requests still need to be filled in before the PDF is generated.
onError error Called if there is an error with the request. Parameter is the response from the AJAX request.

results matching ""

    No results matching ""