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.

Overview

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.createForm() 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 formapi.io 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://formapi.io/assets/embed/data_request.v1.0.0.js"
></script>

<script>
  FormAPI.createForm({
    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 FormAPI.createForm():

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

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

JavaScript API

FormAPI.createForm(cssSelector, optionsAndCallbacks = {})

Or:

FormAPI.createForm(optionsAndCallbacks = {})

Options

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

Callbacks

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".)
onError error Called if there is an error with the request. Parameter is the response from the AJAX request.

results matching ""

    No results matching ""