Signature Requests JavaScript API

The Signature Requests JavaScript library embeds signature request forms on your website for collecting electronic signatures. It was called Data Requests JS until version 3.0.0, which renamed its function and options (see the changelog).

Implementation Guide for Signature Requests Step-by-step guide to implementing UETA and ESIGN compliant electronic signatures

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

DocSpring.createSignatureRequestForm()

Creates an embedded signing form for collecting electronic signatures.

Syntax

DocSpring.createSignatureRequestForm(cssSelector, optionsAndCallbacks);
// or
DocSpring.createSignatureRequestForm(optionsAndCallbacks);

Parameters

Parameter	Type	Required	Description
cssSelector	string	No	CSS selector for the container element where the form will be rendered
optionsAndCallbacks	object	Yes	Configuration options and event callbacks

Required Options

Option	Type	Description
signatureRequestId	string	Your signature request ID
tokenId	string	Your Token ID
tokenSecret	string	Your Token Secret

You can pass signatureRequestURL instead of these three options.

Configuration Options

Option	Type	Default	Description
redirectURL	string	null	Redirect to this URL after submitting the form (overrides the template’s redirect URL)
redirectURLQueryParams	boolean	true	Automatically add submission_id, template_id, and template_name query params to the redirect URL
focusFirstFieldOnLoad	boolean	false	Automatically focus the first field after the form is loaded
showSignatureModalOnFocus	boolean	false	Automatically open the signature/initials popup when a signature or initials field is focused
closeModalOnClickOverlay	boolean	true	Allow the user to close the form by clicking on the modal overlay
closeModalOnSave	boolean	false	Close the modal after the form has been saved
closeModalOnProcessed	boolean	false	Close the modal after the PDF has been processed
loadingTimeout	number	30000	Milliseconds to wait for the signing form to load before calling onError with a load_timeout error
showClearButton	boolean	true	Show the “Clear Form” button
showTermsOfServiceLink	boolean	true	Show a link to DocSpring’s terms of service on the “Accept Terms” screen
allowSkippingOptionalFields	boolean	null	Set to true to show the “Continue” button as soon as every required field is filled in, without first going through each optional field with “Next”. Set to false to always go through the optional fields. Overrides the template’s “Show Continue Once Required Fields Are Filled In” setting, which is used when this is null (Requires version 2.6.0 or above)
termsOfServiceLabel	string	"DocSpring Terms of Service"	Label for the terms of service link
termsOfServiceURL	string	DocSpring ToS	URL for the terms of service link
downloadButtonLabel	string	"Download PDF"	Change the download button label
showDecline	boolean	true	Show the “Decline” button in the form header. Set to false to hide it. (Requires version 2.4.0 or above. Older versions never show the button)
declineButtonLabel	string	"Decline"	Change the label of the “Decline” button shown in the form header (e.g. "Cancel - Do Not Sign")
showPdfProcessingSpinner	boolean	true	Show a spinner while the PDF is being processed
iframeClass	string	null	CSS class for the iframe element
iframeStyle	string	null	Inline styles for the iframe element
footerHTML	string or function	null	Custom HTML content for the footer. A function receives the template object
signatureRequestURL	string	null	Full authenticated signature request URL. Only used when signatureRequestId, tokenId, and tokenSecret are not all provided. Its origin is used to verify messages from the iframe
region	string	US	Use a DocSpring region: US or EU
host	string	null	Use one host for both app and API URLs, usually for single-domain enterprise deployments
appHost	string	null	Override the app host used for the signing iframe, usually for split-domain enterprise deployments
apiHost	string	null	Override the API host used by the visual form inside the signing iframe

Note

When “Submission Privacy” is set to “Private”, the form will redirect or show the thank you message immediately after saving. When it is set to “Public”, the form waits for the PDF to be processed first. If other signature requests on the submission still need to be filled in, the PDF isn’t generated yet, so the form redirects one second after calling onRemainingSignatureRequests, or shows a message saying so if there’s no redirect URL.

Region and Custom Host

Use region when your account is in the EU region:

Regional signature request

DocSpring.createSignatureRequestForm({
signatureRequestId: 'srq_123456',
tokenId: 'tok_123456',
tokenSecret: 'secret_123456',
region: 'EU'
})

For single-domain enterprise deployments, use host. For split-domain deployments, use appHost and apiHost. Existing globals such as DocSpring.region, DocSpring.appHost, DocSpring.apiHost, DocSpring.host, DocSpring.scheme, and DocSpring.port are still supported. If you pass signatureRequestURL without signatureRequestId, tokenId, and tokenSecret, that full URL is used for the iframe and to verify messages from the iframe.

String Options

Customize the titles and messages shown in the header. These options can be either a plain string or a function that returns a string.

Option	Function Arguments	Description
signatureLegalDisclaimerMessage	template (object)	Legal disclaimer text shown below the signature pad when signing
agreeToTermsTitle	template (object), formData (object)	Title for the “Agree to terms of service” step
agreeToTermsMessage	template (object), formData (object)	Message for the “Agree to terms of service” step
waitingForSignatureRequestsTitle	remainingSignatureRequestsCount (number), template (object)	Title when there are still pending signature requests
waitingForSignatureRequestsMessage	remainingSignatureRequestsCount (number), template (object)	Message when there are still pending signature requests
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 data is saved but no download URL is available

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
onDecline	-	Called when the user declines to sign. The signature request and its submission are cancelled, and no PDF is generated
onSubmit	formData (object)	Called when the submit button is pressed
onSave	{ submissionId }	Called when the form has been saved
onProcessed	{ submissionId, downloadURL }	Called when the PDF has been processed (only if “Submission Privacy” is “Public”). If the form redirects, the redirect follows one second later, even if closeModalOnProcessed closes the modal (from version 2.5.0; older versions don’t call it when the form redirects)
onRemainingSignatureRequests	remainingSignatureRequestsCount	Called when other signature requests still need to be filled in (only if “Submission Privacy” is “Public”). If the form redirects, the redirect follows one second later, unless the page closes the form first (for example to show the next signer’s form)
onError	{ error, message }	Called when something goes wrong, with an error code and a message (see Errors)

Errors

onError gets an object with an error code and a message to show or log. A failed save or decline also has the response’s HTTP status.

error	When
frame_blocked	The browser refused to show the signing form. A live signature request only loads on the sites in the template’s Embed Domains setting (see Embedded Signature Requests)
token_expired	The signing link has expired: an api token works for 24 hours and an email token for 7 days. Create a new token
invalid_token	The token ID or secret is wrong, or the token is for another signature request
not_found	The signature request doesn’t exist
signature_request_completed	The signer has already signed
signature_request_declined	The signature request was declined
submission_expired	The document was deleted
save_failed	Saving the signer’s values failed
decline_failed	Declining failed
processing_failed	The PDF couldn’t be generated
processing_timeout	The PDF is taking more than a minute to generate. Sent once: the form keeps waiting for it
load_timeout	The signing form didn’t load within loadingTimeout
message_timeout	The signing form didn’t confirm a message from your page
internal_error	Something went wrong on our side when the signing form opened
unknown_error	Anything else

Data Requests JS (before 3.0.0) passes a string, or nothing when the PDF couldn’t be generated.

Global Functions

These global functions allow you to interact with the form. If a page opens more than one form, they act on the most recently opened form that is still open (from version 2.5.0).

Function	Parameters	Description
DocSpring.clearForm()	-	Clear all data on the form and reset to default values
DocSpring.focusNextField()	-	Focus the next field (same as clicking “Next” button)
DocSpring.focusField(name_or_id)	name_or_id: Field name or numeric ID	Focus a specific field
DocSpring.returnToForm()	-	Return to the form after it has been submitted
DocSpring.closeModal()	-	Close every signature request form shown in a modal

Examples

Basic Usage

Basic signature request form

DocSpring.createSignatureRequestForm({
    signatureRequestId: 'srq_123456',
    tokenId: 'tok_123456',
    tokenSecret: 'secret_123456'
})

With Custom Options

Signature request with options

DocSpring.createSignatureRequestForm('.form-container', {
  // Required options
  signatureRequestId: 'srq_123456',
  tokenId: 'tok_123456',
  tokenSecret: 'secret_123456',

  // UI customization
  downloadButtonLabel: 'Get My Document',
  showSignatureModalOnFocus: true,

  // Callbacks
  onSubmit: function(formData) {
    console.log('Form submitted:', formData);
  },

  onProcessed: function(data) {
    console.log('PDF ready:', data.downloadURL);
  },

  onError: function(error) {
    console.error('Error:', error.error, error.message);
  }

})

Custom Footer

Custom footer buttons

DocSpring.createSignatureRequestForm({
  signatureRequestId: 'srq_123456',
  tokenId: 'tok_123456',
  tokenSecret: 'secret_123456',

  footerHTML: function(template) {
    return '<div class="dsp-footerLeft">' +
      '<button class="dsp-button dsp-primaryButton" onclick="customSave()">Save Draft</button>' +
    '</div>' +
    '<div class="dsp-footerRight">' +
      '<button class="dsp-button" onclick="customCancel()">Cancel</button>' +
    '</div>';
  }

})

Custom Messages

Custom messages

DocSpring.createSignatureRequestForm({
  signatureRequestId: 'srq_123456',
  tokenId: 'tok_123456',
  tokenSecret: 'secret_123456',

  // Custom messages
  signatureLegalDisclaimerMessage: 'By signing, I agree to the terms.',

  agreeToTermsTitle: function(template, formData) {
    return 'Please Review and Sign ' + template.name;
  },

  completedTitle: function(template, downloadURL) {
    return 'Your ' + template.name + ' is Ready!';
  },

  pdfProcessedMessage: 'Your document has been generated successfully.'

})

Debugging

Enable debug logging to troubleshoot issues:

DocSpring.DEBUG = true;

This will 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.

Browser Compatibility

The Signature Requests JavaScript library supports all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Older versions of Internet Explorer are not supported.