Template Settings

Click Settings in the template editor’s top bar to change a template’s settings. They’re in tabs: General, PDF output, Forms, Submissions, Embedding, Webhooks, Emails, Field defaults and Advanced. Each setting below says which tab it’s on.

The Field defaults tab sets the typeface, colors, date formats and other options that fields use when they don’t set their own.

Locked

On the General tab. Locked templates cannot be changed or deleted. See Locked Templates.

Expire Submissions

On the Submissions tab. The Expire submissions setting allows you to configure a data retention policy for your submissions.

• If Expire submissions is unchecked (the default), we will store all submission data and generated PDFs indefinitely. (Nothing will ever be deleted automatically.)
• If Expire submissions is checked, we will automatically delete all submission data and metadata, generated PDFs, any uploaded images, and the submitter’s IP address, browser and location after a certain period of time. The expiration time is set beside it (5 minutes, 24 hours, 7 days, etc.)

A submission that fails (for example, with invalid data) is kept for at least 48 hours before it expires, even if the expiration time is shorter, so that you can see what went wrong and a retry still has its data.

(Please note that electronic signatures and a SHA256 hash of the PDF are always retained for UETA and ESIGN compliance.)

You can also make an API request to immediately expire a submission.

Allow Additional Properties

On the Submissions tab. By default, the data that you submit must exactly match the JSON schema. Any additional properties will cause a validation error. This guarantees that you haven’t forgotten to add any fields to your template, and it also guards against accidental field deletion.

When the Allow additional properties in JSON data setting is enabled, additional properties in your data will be silently ignored. This can be useful when you don’t have full control over the JSON data (e.g. a webhook integration with a third-party service.) A misspelled field name is ignored too: its field is left blank, or the submission fails if that field is required.

Encrypt PDFs with a Password

On the PDF output tab. When Encrypt PDFs with a password is checked, generated PDFs are encrypted with the PDF password, and can only be opened by entering that password. (This is called a “user password”.)

Merge Audit Trail With Signature Request PDFs

On the PDF output tab, for PDF templates only. When checked, audit trail pages are appended to the generated PDF when a submission has signature requests. When unchecked, the audit trail PDF can be downloaded separately.

Add Submission ID Footers to Signature Requests

On the PDF output tab, for PDF templates only. When checked, the submission ID is added to the bottom right corner of each page when a submission has signature requests.

Parse Dates Using the Template’s Date Format

On the Field defaults tab, for PDF templates only. This setting is under the default date formats (Parse dates using format).

We recommend sending date values as YYYY-MM-DD (see Date). Dates sent as numbers like 05/07/2024 (with slashes, dashes or dots) are read day first by default, so 05/07/2024 is July 5, and a date like 05/13/2024 can’t be read and is left blank.

When Parse dates using format is checked, these dates are read in the same order as the template’s default Date format: month first for %m/%d/%Y, and day first for %d/%m/%Y. Fields that include a time use the default Date/time format. Dates sent as YYYY-MM-DD are read the same way either way.

Each template version keeps its own setting. If your template has published versions, publish a new version after changing it: API submissions use the latest published version by default (see Template Versions).

You can also set this for new templates on your account’s Template defaults page, and change it with the parse_dates_using_template_date_format option in the templates API.

HTML Page Settings

On the PDF output tab. HTML templates have Page format, Landscape, Width, Height, margin and Print background settings. See Page Settings.

Online Form Privacy

On the Forms tab. Set this to Public to allow anyone to fill out the online form if they have the URL.

Online Form

On the Forms tab, as Form type. Which form a PDF template’s online form link opens: the web form (questions on a page), the visual form (fields filled in on the PDF), or both, in two tabs. A mode parameter in the link overrides it (see Web Form, Visual Form or Both). HTML templates don’t have this setting: they have no visual form, so they always show the web form.

You can also set this on your account’s Template defaults page, for new templates and, with Update Templates, for existing ones. HTML templates stay on the web form either way.

Show Continue Once Required Fields Are Filled In

On the Forms tab, for PDF templates only. Visual forms and signature requests have a Next button that takes the user through each field in turn. By default, while the user is in a field, the Continue button only replaces it once every field has a value or has been visited. Check this setting to show Continue as soon as every required field is filled in, so users can skip the optional fields. The allowSkippingOptionalFields option of Visual Forms JS and Signature Requests JS overrides this setting either way.

Submission Privacy

On the Submissions tab. Set this to Public to allow anyone to view submission data and download their PDF if they have the URL.

This is useful when you have added a @@data_url QR code to the PDF. (@@data_url is a URL where the submission data can be viewed or downloaded.)

Webhook URL

Configure webhooks on the Webhooks page. See Webhooks Overview.

Existing legacy webhook URLs on templates and API tokens (shown on the Webhooks tab as Legacy webhook URL) keep working until they are migrated to the new webhooks system.

Slack Webhook URL

On the Webhooks tab. Posts a message to a Slack channel whenever this template generates a PDF. Each message links to the PDF and to its submission. Test PDFs and combined PDFs don’t post a message.

To get a URL, create a Slack app with an incoming webhook for the channel (Slack’s guide), then paste the webhook URL into this field. Messages show your Slack app’s name and icon.

On the free Developer plan, each Slack webhook URL is one of the account’s 2 active integrations. Using the same URL on more templates doesn’t count again.

Email Actions

On the Emails tab. Email each submission’s PDF to the people who filled it in, or to your team, with your own subject and message. See Email Actions.

Signature Request Emails

On the Emails tab, for PDF templates only. How DocSpring emails the people who sign this template’s signature requests. A request’s own reply_to and notification_emails replace the template’s. You can set them for new templates on your account’s Template defaults page, and with the signature_request_* options in the templates API.

• Sender name: Who your signers see the emails are from, as in “Acme via DocSpring”. Leave it empty to use your account’s name.
• From address: Growth and Scale plans. An address at one of your verified email domains, the same domains as email actions. Leave it empty to send from DocSpring’s shared address, with “via DocSpring” after the sender name. While the address can’t be used (its domain is no longer verified, or your plan no longer includes it), new signature requests that DocSpring emails are refused until you change it. Emails for requests created before that go from the shared address, and your account owner gets an email.
• Signing URL: Growth and Scale plans. A page on your own site that the email’s button opens instead of DocSpring’s signing page: an https URL on one of your verified email domains or a subdomain of one. It must include {{ signature_request_id }}. Your page checks who the signer is, then creates a token and opens the signing form. The audit trail still says the signer was authenticated by an email link (email_link): DocSpring emailed the link to their address, whichever page it opens. While the URL can’t be used (its domain is no longer verified, or your plan no longer includes it), new signature requests that DocSpring emails are refused until you change it, and emails with a link for earlier requests aren’t sent. Your notification emails get an email about it.
• Include the signing token: Adds a signing token to the signing URL, as {{ token_id }} and {{ token_secret }}, so your page can open the signing form without creating a token. Anyone who has the email can then sign, as with DocSpring’s own link.
• Reply-to address: Where your signers’ replies go: a team member’s address, or one at your verified email domains. Leave it empty to use your account owner’s.
• Notification emails: Who DocSpring emails when a document is completed or declined, or an email to a signer bounces or can’t be sent. Up to 10 team members or addresses at your verified email domains. Leave it empty to email your account owner.
• Signed PDF: How the emails that send signers and CCs the signed PDF include it: attached (a download link when it’s too big to attach), or a download link. The default is a link if your account has signed a BAA, otherwise attached. An email action that sends the PDF to one of these people replaces DocSpring’s email to them.

Redirect URL

On the Forms tab. We’ll redirect users to this URL whenever they fill out the online form to generate a PDF. This applies to online forms hosted on docspring.com, and embedded forms on your own website. The submission ID, template ID, and template name will be appended to the URL as query params.

Template Description

On the General tab. The template description is shown under the template’s name at the top of its online form, in every mode, and is the page’s meta description. It is not shown on embedded forms or signature requests.

Embedded Template Editor Settings

These are on the Embedding tab.

• Embed domains: Not shown in the embedded editor. A comma-separated list of domains where you embed the template editor or signature request forms. The template editor accepts wildcards such as *.example.com and isn’t restricted when the list is blank (see Embed Domains). Live embedded signature requests only load on the listed sites, accept the same wildcards and ports, and don’t load on any site when the list is blank; test signature requests load anywhere.
• Embed edit token: Not shown in the embedded editor. The token you use with template_editor.js to embed this template editor. You can show or regenerate it. See Embed Edit Token.
• Embedded editor permissions: Not shown in the embedded editor. Allow embedded editor users to change template settings, to publish, restore, and delete versions, or to replace the PDF document. By default they can only edit fields and layout. See Security.
• Predefined fields: PDF templates only. The field names that embedded editor users can add. See Use Predefined Fields.

Template PDF

On the General tab, for PDF templates only. Shows the template’s PDF file. Drop a new PDF onto the upload area to replace it. The template keeps its fields.

To replace the fields too, check Re-import fields from the new PDF before you drop the new PDF. When the PDF has been processed, all of the template’s fields are replaced with the fillable fields in the new PDF, the same way as when you first uploaded a PDF (the fields can’t be edited until then). Fields you added or changed in DocSpring are removed. The default typeface, font size, bold and color are taken from the new PDF’s fields, and the template’s other settings are kept. Click Undo in the message that appears to put the previous fields and defaults back. If the new PDF has no fillable fields, the template keeps its fields.

With the API, send the new PDF with reimport_fields set to true: PUT /templates/{template_id}/document takes a document_url, document_base64 or an uploaded cache_id, and PUT /templates/{template_id}/document/upload takes a multipart upload. In our API clients, these are updateTemplateDocument and uploadTemplateDocument. A re-import isn’t allowed on a locked template.