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. DocSpring emails each person a link to sign, or you can send them the links yourself, or embed the form on your own website. When everyone has filled in the form, the PDF will be generated, DocSpring emails it to the people who signed, and we can send your server a webhook notification.

Signature requests work with PDF templates: signers fill in and sign the fields on the template’s pages. HTML templates, Word templates and page designs can’t have signature requests yet.

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

When DocSpring sends the emails (the default):

1. Create a submission with signature requests: the people who fill in and sign the document, and optionally the order they sign in, a message and reminders. See Emails from DocSpring.
2. DocSpring emails each person a link to its signing page, and reminds them if you asked it to.
3. Each person signs on the signing page.
4. DocSpring generates the PDF and emails it to the people who signed and to any CCs. Your server gets webhook notifications along the way.

When you send the links yourself or embed the form in your app, create the signature requests with send_email: false:

1. Create a submission with signature requests: include details about the people who will be filling out and signing the document, and how your app authenticated them.
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: make sure the 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 WorkCredit 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 DocSpring emailed the signing link or a reminder, and when that email bounced or was marked as spam.
• When you sent the signing link yourself, 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 reported by your account. When a signer opens an email link, DocSpring records the time itself, and when the link was one DocSpring emailed, the section says DocSpring sent it to the signer’s address.
• 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

Your Logo and Brand Color

The signing page, DocSpring’s emails to your signers and the audit trail show your account’s logo, and the signing page and emails use your brand color for their buttons. Set them in the Logo and Brand color fields on the Account page. They show when your account is on a paid plan or has bought a credit pack. On the signing page, the logo shows when the page is opened from its link, not when you embed the form on your own site.

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 GuideComplete tutorial for implementing signature requests

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

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