Create Document from Template

post

https://www.signwell.com/api/v1/document_templates/documents

Creates and optionally sends a new document for signing. If draft is set to true the document will not be sent. Pre-signed template signatures and initials are copied to the new document as document content — they remain visible on the document but do not generate a signing event, do not emit a document_signed webhook, and the recipient's status will not reflect them as a real signing action. If the template was pre-signed for a signer and the request adds new unsigned signature/initials fields for that same signer, the pre-applied ratifications are cleared silently so the signer is asked to sign once. Recipients are notified by email, SMS, or both based on each recipient's delivery_method. SMS delivery is available only to workspaces that are eligible for SMS and have it enabled, and requires a phone_number in E.164 format.

Body Params

test_mode

boolean

Defaults to false

Set to true to enable Test Mode. Documents created with Test Mode do not count towards API billing and are not legally binding. Defaults to false

send_sms_test_preview_email

boolean

Defaults to false

Only applies when test_mode is true. When true, and the document has an SMS-only recipient, sends the document owner a test-mode preview email (with a masked phone number) instead of the regular SMS sender-copy email. No SMS is sent and no credits are used, in test mode or otherwise. Defaults to false.

template_id

uuid

Use when you have to create a document from a single template. Either :template_id or :template_ids must be present in the request, not both.

template_ids

array of strings

Use when you have to create a document from multiple templates. Either :template_id or :template_ids must be present in the request, not both.

template_ids

name

string

The name of the document.

subject

string

Email subject for the signature request that recipients will see. Defaults to the default system subject or a template subject (if the document is created from a template). Applies to email notifications only; SMS notifications always use fixed system templates.

message

string

Email message for the signature request that recipients will see. Defaults to the default system message or a template message (if the document is created from a template). Applies to email notifications only; SMS notifications always use fixed system templates.

recipients

array of objects

required

Document recipients are people that must complete and/or sign a document. Recipients of the document must be assigned to a placeholder of the template. Recipients will inherit all placeholder fields and settings.

recipients*

exclude_placeholders

array of strings

Exclude one or more template placeholders when creating a document from a template. Any excluded placeholders (and their associated recipients and fields) will not be included on the created document. Values must match placeholder names on the template. You can't exclude all placeholders (at least one recipient must remain).

exclude_placeholders

draft

boolean

Defaults to false

Whether the document can still be updated before sending a signature request. If set to false the document is sent for signing as part of this request. Defaults to false.

with_signature_page

boolean

Defaults to false

When set to true the document will have a signature page added to the end, and all signers will be required to add their signature on that page.

expires_in

integer

≥ 1

Number of days before the signature request expires. Defaults to the account expiration setting or template expiration (if the document is created from a template).

reminders

boolean

Defaults to true

Whether to send signing reminders to recipients. Reminders are sent on day 3, day 6, and day 10 if set to true. Defaults to true.

apply_signing_order

boolean

Defaults to false

When set to true recipients will sign one at a time in the order of the recipients collection of this request.

api_application_id

uuid

Unique identifier for API Application settings to use. API Applications are optional and mainly used when isolating OAuth apps or for more control over embedded API settings

embedded_signing

boolean

Defaults to false

When set to true it enables embedded signing in your website/web application. Embedded functionality works with an iFrame and email authentication is disabled. :embedded_signinig defaults to false.

embedded_signing_notifications

boolean

Defaults to false

On embedding signing, document owners (and CC'd contacts) do not get a notification email when documents have been completed. Setting this param to true will send out those final completed notifications. Default is false

text_tags

boolean

Defaults to false

An alternative way (if you can’t use the recommended way) of placing fields in specific locations of your document by using special text tags. Useful when changing the content of your files changes the location of fields. See API documentation for “Text Tags” for details. Defaults to false.

custom_requester_name

string

Sets the custom requester name for the document. When set, this is the name used for all email communications, signing notifications, and in the audit file.

custom_requester_email

string

Sets the custom requester email for the document. When set, this is the email used for all email communications, signing notifications, and in the audit file.

redirect_url

url

A URL that recipients are redirected to after successfully signing a document.

allow_decline

boolean

Defaults to true

Whether to allow recipients the option to decline signing a document. If multiple signers are involved in a document, any single recipient can cancel the entire document signing process by declining to sign.

allow_reassign

boolean

Defaults to true

In some cases a signer is not the right person to sign and may need to reassign their signing responsibilities to another person. This feature allows them to reassign the document to someone else.

decline_redirect_url

url

A URL that recipients are redirected to if the document is declined.

language

string

Sets the language for all recipients on the document and updates all recipient side interactions including the document email and the document itself. Accepted languages: English, Français, Español, Deutsch, Polski, Português, Dansk, Nederlands, Italiano, Русский, Svenska, العربية, Ελληνικά, Türkçe, Slovenčina. Defaults to English. Language should be sent in ISO 639-1 format: en, fr, es, de, pl, pt, da, nl, it, ru, sv, ar, el, tr, sk.

conditional_rules

array of objects

Conditional logic rules that show, hide, or require fields based on what a signer does to other fields. Every identifier is a field api_id. At most 10 rules per document or template.

conditional_rules

conditional_rules_mode

string

enum

When creating a document from a template, controls how the conditional_rules in the request reconcile with the template's inherited rules: replace (drop inherited, use the body's rules), append (keep inherited, add the body's rules), or none (clear all rules). Required when sending conditional_rules that should not simply inherit.

Allowed:

metadata

object

Optional key-value data that can be associated with the document. If set, will be available every time the document data is returned.

template_fields

array of objects

Fields of your template(s) that you can prepopulate with values. Signature and Initials fields cannot be signed through the API.

template_fields

files

array of objects

files

fields

array of arrays of objects

Fields to be added to any appended files (not existing files). Document fields placed on a document for collecting data or signatures from recipients. Field data should be sent as a 2-dimensional JSON array. One array of fields is needed for each file in the files array. An array of fields can be empty if you have a file that does not contain any fields.

fields

attachment_requests

array of objects

Attachments that a recipient must upload to complete the signing process. Attachment requests are shown after all document fields have been completed.

attachment_requests

copied_contacts

array of objects

Copied contacts are emailed the final document once it has been completed by all recipients.

copied_contacts

labels

array of objects

Labels can be used to organize documents in a way that can make it easy to find using the document search in SignWell. A document can have multiple labels. Updating labels on a document will replace any existing labels for that document.

labels

checkbox_groups

array of objects

Checkbox fields that are placed on a document can be grouped with selection requirements. At least 2 checkbox fields in an array of fields must be assigned to the same recipient.

checkbox_groups

Responses

201created

400bad request

422unprocessable entity

429rate limit exceeded