Signature Requests

Collect legally binding electronic signatures

Create a signature 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 or initials fields). The PDF submission will be in a pending state until all of its signature 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.

How Signature Requests Work

Here is an overview of the process:

1. Create a submission with signature requests - Include details about the people who will be filling out and signing the document
2. Send notification emails - Send your users links to the signing form and record the event
3. Request authentication tokens - Create a token when the user is ready to sign
4. Update authentication details - Ensure authentication information is current
5. Render the signing form - Embed the form on your website or use the hosted signing page
6. Process the completed PDF - Receive webhook notifications when all signatures are collected

This process ensures that DocSpring can record a complete audit trail of events, making all electronic signatures legally binding.

A signed PDF never has editable form fields, so nobody can change a value after it was signed. When a signature request asks someone to sign or initial, every field in the final PDF is static, even if the submission sets editable: true or the template generates editable PDFs (Editable PDFs).

Declining to Sign

A signer can choose not to sign by clicking the Decline button in the form header. The button is shown on the signing page that a signature request token’s signature_request_url opens (data_request_url in API v1), and when you embed the signing form with Signature Requests JS version 2.4.0 or above (older versions don’t show it). In an embedded form, you can hide the button with the showDecline: false option, or rename it with the declineButtonLabel option (for example, "Cancel - Do Not Sign").

Declining can’t be undone:

• The signature request moves to the declined state, and a decline_request event is recorded with the signer’s IP address and browser.
• The entire submission is cancelled. It moves to the declined state and no PDF is generated, even if other signers have already signed.
• DocSpring sends the submission.declined and submission_data_request.declined webhook events. Webhooks created with API v2 receive the second one as signature_request.declined.

Once a submission has been declined, its remaining signature requests can no longer be opened or signed.

If you read submissions or signature requests with a DocSpring API client, upgrade it to the latest version. Older versions of the Ruby, Python, PHP, Java and C# clients raise an error when they read the declined state.

Credit Usage

The final live PDF costs its own generation credits plus 60 credits for each signature request that asks its signer to sign or initial. Signature requests that only collect values, such as text, numbers and dates, add nothing: you pay only for the PDF. There is no separate charge for creating a request, issuing access tokens, recording events, or generating previews. Watermarked test submissions are free.

How Credits Work Credit calculations and examples for signed PDFs

Signature Request Components

Authentication Requirements

To ensure legal compliance, signature requests should include:

• The user’s name and email address. Both are optional, but we recommend including them because they are shown on the audit trail.
• Details about how and when the user was authenticated (auth_type is required)
• The fields that the user must fill out (including signature or initials fields)
• Optional metadata to save on the signature request

Tip

While many authentication fields are optional, provide as much detail as you can. This helps DocSpring build a comprehensive audit trail and ensures electronic signatures will be legally binding if contested in court.

Audit Trail

DocSpring automatically records a complete audit trail for each signature request, including:

• When you sent the signing link, which you report through the Create Signature Request Event API. The audit trail shows it as reported by your account.
• How and when each signer was authenticated, in a Signer Authentication section. These are the details you sent, shown as stated by your account. When a signer opens an email link, DocSpring records the time itself.
• When the document was viewed
• When each signature was collected
• When the document was completed

The certificate also shows the document’s Document SHA-256, the hash of the document before the certificate and any password were added, and an Audit trail hash of the certificate’s details and events.

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

Authentication Tokens

Authentication tokens authorize a user to access and sign a specific signature request. Key characteristics:

• Its link opens the signing form for 24 hours (api tokens, the default) or 7 days (email tokens, for links you send by email). A form that opened in time keeps working for 7 more days, so the person can finish it later. After that, the page says the link has expired and to ask the sender for a new one.
• Can’t be created once the signature request is finished (completed, declined, or expired). The API returns an error, and the same applies to updating the signature request or adding events to it.
• Should be requested immediately before showing the signing form
• Include an authenticated URL for the hosted signing page

Mobile Support

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

Caution

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

Related Resources

Step-by-Step Implementation Guide Complete tutorial for implementing signature requests

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

Create Signature Requests API Guide Learn how to create PDF submissions with pending signature requests