---
title: "Create Template"
method: POST
path: "/api/v1/document_templates"
tags: ["Template"]
---

# Create Template

`POST /api/v1/document_templates`

Creates a new template.

## Request body

- DocumentTemplateRequest
  - `files` object[], required — Document files can be uploaded by specifying a file URL or base64 string. Either `file_url` or `file_base64` must be present (not both). Valid file types are: .pdf, .doc, .docx, .pages, .ppt, .pptx, .key, .xls, .xlsx, .numbers, .jpg, .jpeg, .png, .tiff, .tif, .webp, .html, and .htm
    - `name` string, required — Name of the file that will be uploaded.
    - `file_url` string, url — Publicly available URL of the file to be uploaded.
    - `file_base64` string, byte — A RFC 4648 base64 string of the file to be uploaded.
  - `name` string — The name of the template.
  - `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).
  - `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).
  - `placeholders` object[], required — Placeholders are generally job roles that must complete and/or sign the document. For example, a placeholder might be “Client” or “Legal Department”. When a document is created from the template, you assign a person to each placeholder.
    - `id` string, required — A unique identifier that you will give to each placeholder. We recommend numbering sequentially from 1 to X. IDs are required for associating recipients to fields and more.
    - `name` string, required — Name of the placeholder.
    - `preassigned_recipient_name` string — In some cases, it may be necessary to pre-fill the name and email for a placeholder because it will always be the same person for all documents created from this template. This sets the name.
    - `preassigned_recipient_email` string, email — In some cases, it may be necessary to pre-fill the name and email for a placeholder because it will always be the same person for all documents created from this template. This sets the email.
    - `passcode_delivery` object — Passcode delivery (OTP) settings for this placeholder. When enabled, documents created from this template inherit these settings for the corresponding recipient.
      - `enabled` boolean — Enable passcode delivery for this recipient.
      - `methods` string[] — Delivery methods for the passcode. Currently supports: email. Defaults to ["email"] when omitted.
      - `expire_after_access` boolean — Whether the passcode expires after the recipient accesses the document. Inherited by documents created from this template.
  - `copied_placeholders` object[] — Copied placeholders are emailed the final document once it has been completed by all recipients.
    - `name` string, required — Name of the placeholder.
    - `preassigned_recipient_name` string — In some cases, it may be necessary to pre-fill the name and email for a placeholder because it will always be the same person for all documents created from this template. This sets the name.
    - `preassigned_recipient_email` string, email — In some cases, it may be necessary to pre-fill the name and email for a placeholder because it will always be the same person for all documents created from this template. This sets the email.
  - `draft` boolean — Whether the template can still be updated before it is ready for usage. If set to `false` the template is marked as `Available` and it will be ready for use. Defaults to `false`.
  - `expires_in` integer — 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 — 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 — When set to `true` recipients will sign one at a time in the order of the `recipients` collection of this request.
  - `api_application_id` string, 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
  - `text_tags` boolean — 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.
  - `redirect_url` string, url — A URL that recipients are redirected to after successfully signing a document.
  - `allow_decline` boolean — 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 — 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` string, url — A URL that recipients are redirected to if the document is declined.
  - `language` string — Sets the language for the template and documents created from the template for 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. 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` ConditionalRuleRequest[] — 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.
    - `id` string — The rule's persistent ID. Ignored on create (every rule is new). On an update (template update or document update-and-send) include it to modify an existing rule, or pair it with `deleted: true` to remove the rule; omit it to add a new rule.
    - `deleted` boolean — Only meaningful on an update (template update or document update-and-send): set to true together with the rule's `id` to remove that rule. Ignored on create — there is no existing rule to delete.
    - `target_id` string — api_id of the field that owns the rule, or the external_id of a checkbox group when the rule is owned by a group (groups have no api_id). Cannot also appear in action_field_ids (self-reference is forbidden).
    - `action_type` 'show' | 'hide' | 'require' — Action applied to action_field_ids when the conditions are met: `show`, `hide`, or `require`.
    - `action_field_ids` string[] — api_ids of the fields the action applies to. List a checkbox group's member api_ids to target the whole group.
    - `conditions` object[] — The conditions that trigger the rule. At least 1, at most 5.
      - `condition_type` 'any_of' | 'all_of' | 'none_of' | 'not_all_of', required — How the field_api_ids combine within a condition: `any_of`, `all_of`, `none_of`, or `not_all_of`.
      - `status` 'completed' | 'not_completed', required — The field state the condition tests for: `completed` or `not_completed`.
      - `join_operator` 'and_operator' | 'or_operator' — How this condition joins the next one in the rule: `and_operator` or `or_operator`. The first condition's value is ignored.
      - `field_api_ids` string[], required — api_ids of the trigger fields the condition watches.
      - `position` integer — 1-indexed order of the condition within the rule.
  - `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.
  - `fields` array[] — Document fields placed on a document for collecting data or signatures from recipients. At least one field must be present in the Create Document request if `draft` is `false` (unless adding a signature page by using `with_signature_page`). 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.
    - object[] — Array of Fields you're adding to each file.
      - `x` number, float, required — Horizontal value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located.
      - `y` number, float, required — Vertical value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located.
      - `page` integer, required — The page number within the file. If the page does not exist within the file then the field won't be created.
      - `placeholder_id` string, required — Unique identifier of the placeholder assigned to the field.
      - `type` 'initials' | 'signature' | 'checkbox' | 'date' | 'select' | 'text' | 'dropdown' | 'autofill_company' | 'autofill_email' | 'autofill_first_name' | 'autofill_last_name' | 'autofill_name' | 'autofill_phone' | 'autofill_title' | 'autofill_date_signed', required — Type of signing field
      - `required` boolean — Whether the field must be completed by the recipient. Defaults to `true` except for checkbox type fields.
      - `label` string — Text and Date fields only: label that is displayed when the field is empty.
      - `value` union — Varies according to the field type. Text fields accept strings or numbers. Date fields accept Iso8601 date strings. CheckBoxes accept booleans. Signature and Initials fields can't be signed through API requests. Autofill text fields accept strings or numbers.
        - string
        - boolean
        - number
      - `api_id` string — Unique identifier of the field. Useful when needing to reference specific field values or update a document and its fields.
      - `name` string — Checkbox fields only. At least 2 checkbox fields in an array of fields must be assigned to the same recipient and grouped with selection requirements.
      - `validation` 'no_text_validation' | 'numbers' | 'letters' | 'email_address' | 'us_phone_number' | 'us_zip_code' | 'us_ssn' | 'us_age' | 'alphanumeric' | 'us_bank_routing_number' | 'us_bank_account_number' | 'custom' — Validation rule for text fields
      - `validation_regex` string — Text fields with custom validation only: the regex pattern used to validate field values. Required when validation is set to custom.
      - `validation_regex_error_message` string — Text fields with custom validation only: the error message shown to the recipient when their input doesn't match the regex pattern. Required when validation is set to custom.
      - `fixed_width` boolean — Text fields only: whether the field width will stay fixed and text will display in multiple lines, rather than one long line. If set to `false` the field width will automatically grow horizontally to fit text on one line. Defaults to `false`.
      - `lock_sign_date` boolean — Date fields only: makes fields readonly and automatically populates with the date the recipient signed. Defaults to `false`.
      - `date_format` 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY/MM/DD' | 'Month DD, YYYY' | 'MM/DD/YYYY hh:mm:ss a' — Date format for date fields. Valid values: MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD, Month DD, YYYY, MM/DD/YYYY hh:mm:ss a. Default: MM/DD/YYYY
      - `height` number, float — Height of the field (in pixels). Maximum height varies by field type: Signature/Initials (200px), others (74px). When using text tags if the height is greater than the maximum height, the height will be set to the maximum height.
      - `width` number, float — Width of the field (in pixels). For text fields, width will auto-grow unless `fixed_width` is true.
      - `options` DropdownOption[] — Array of dropdown options (for dropdown/select fields only)
        - union — A dropdown option - either a simple string or a detailed object with name and optional api_id
          - string — Simple string option
          - object — Detailed option object
            - `name` string, required — Option display name
            - `api_id` string — Unique identifier for the option
            - `is_other` boolean — Whether this is the special "Other" option
      - `default_option` string — Default selected option (for dropdown/select fields only)
      - `allow_other` boolean — Whether to allow "Other" option with text input (for dropdown/select fields only)
  - `attachment_requests` object[] — Attachments that a recipient must upload to complete the signing process. Attachment requests are shown after all document fields have been completed.
    - `name` string, required — Name of the requested attachment.
    - `placeholder_id` string, required — Unique identifier of the recipient that will view the attachment request.
    - `required` boolean — Whether the recipient will need to upload the attachment to successfully complete/sign the document. Defaults to `true`.
  - `labels` LabelRequest[] — 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.
    - `name` string, required
  - `checkbox_groups` object[] — 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.
    - `group_name` string, required — A unique identifier for the checkbox group.
    - `placeholder_id` string, required — The recipient ID associated with the checkbox group.
    - `checkbox_ids` string[], required
    - `validation` 'minimum' | 'maximum' | 'range' | 'exact' — Validation rule for checkbox groups
    - `required` boolean — Whether the group must be completed by the recipient. Defaults to false.
    - `min_value` integer — The minimum number of checkboxes that must be checked in the group. (Only for validation: minimum and range)
    - `max_value` integer — The maximum number of checkboxes that can be checked in the group. (Only for validation: maximum and range)
    - `exact_value` integer — The exact number of checkboxes that must be checked in the group. (Only for validation: exact)

## Response `201`

created

- DocumentTemplateResponse
  - `id` string, required
  - `api_application_id` string, uuid, nullable
  - `requester_email_address` string, email
  - `custom_requester_name` string, nullable
  - `custom_requester_email` string, email, nullable
  - `name` string
  - `subject` string
  - `message` string
  - `metadata` object, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `placeholders` object[]
    - `id` string
    - `name` string, required
    - `subject` string, nullable
    - `message` string, nullable
    - `preassigned_recipient_name` string
    - `preassigned_recipient_email` string
    - `signing_order` integer
    - `attachment_requests` AttachmentRequestInfo[]
      - `name` string, required — Name of the attachment request
      - `url` string, url — URL of the uploaded attachment (when available)
      - `required` boolean, required — Whether the attachment is required
    - `passcode_delivery` object
      - `enabled` boolean
      - `methods` string[], nullable
      - `expire_after_access` boolean
  - `copied_placeholders` object[]
    - `id` string
    - `placeholder_id` string
    - `name` string, required
    - `subject` string, nullable
    - `message` string, nullable
    - `preassigned_recipient_name` string
    - `preassigned_recipient_email` string
  - `status` string
  - `reminders` boolean, nullable
  - `archived` boolean
  - `embedded_edit_url` string, url, nullable
  - `template_link` string, url
  - `template_id` string, nullable
  - `apply_signing_order` boolean
  - `redirect_url` string, url, nullable
  - `decline_redirect_url` string, url, nullable
  - `language` string
  - `expires_in` integer, nullable
  - `files` FileInfo[]
    - `name` string, required — File name
    - `pages_number` integer, required — Number of pages in the file
  - `fields` array[]
    - object[]
      - `x` number, float, required
      - `y` number, float, required
      - `page` integer, required
      - `recipient` object
        - `email` string, email, required
        - `name` string, required
      - `api_id` string, uuid
      - `name` string, nullable
      - `date_format` 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY/MM/DD' | 'Month DD, YYYY' | 'MM/DD/YYYY hh:mm:ss a' — Date format for date fields. Valid values: MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD, Month DD, YYYY, MM/DD/YYYY hh:mm:ss a. Default: MM/DD/YYYY
      - `fixed_width` boolean
      - `formula` string
      - `label` string
      - `lock_sign_date` boolean
      - `required` boolean
      - `type` 'initials' | 'signature' | 'checkbox' | 'date' | 'select' | 'text' | 'dropdown' | 'autofill_company' | 'autofill_email' | 'autofill_first_name' | 'autofill_last_name' | 'autofill_name' | 'autofill_phone' | 'autofill_title' | 'autofill_date_signed' — Type of signing field
      - `validation` 'no_text_validation' | 'numbers' | 'letters' | 'email_address' | 'us_phone_number' | 'us_zip_code' | 'us_ssn' | 'us_age' | 'alphanumeric' | 'us_bank_routing_number' | 'us_bank_account_number' | 'custom' — Validation rule for text fields
      - `validation_regex` string — Text fields with custom validation only: the regex pattern used to validate field values. Required when validation is set to custom.
      - `validation_regex_error_message` string — Text fields with custom validation only: the error message shown to the recipient when their input doesn't match the regex pattern. Required when validation is set to custom.
      - `value` union
        - string
        - boolean
        - number
      - `height` string
      - `width` string
      - `recipient_id` string, nullable
      - `signing_elements_group_id` string, uuid
      - `placeholder_name` string
      - `options` object[] — Dropdown options (for dropdown/select fields)
        - `name` string
        - `api_id` string
        - `is_other` boolean
      - `default_option` string — Default selected option
      - `allow_other` boolean — Whether "Other" option is allowed
  - `allow_decline` boolean, nullable
  - `allow_reassign` boolean, nullable
  - `labels` LabelInfo[]
    - `id` string — Label ID
    - `name` string — Label name
  - `checkbox_groups` CheckboxGroupInfo[]
    - `id` string, uuid, required — Checkbox group ID
    - `group_name` string, nullable — Name of the checkbox group
    - `recipient_id` string, nullable — Recipient ID associated with the group
    - `checkbox_ids` string[], required — IDs of checkboxes in this group
    - `validation` 'minimum' | 'maximum' | 'range' | 'exact' — Validation rule for checkbox groups
    - `required` boolean, required — Whether at least one checkbox must be checked
    - `min_value` integer — Minimum number of checkboxes to check
    - `max_value` integer — Maximum number of checkboxes to check
    - `exact_value` integer — Exact number of checkboxes that must be checked
  - `conditional_rules` ConditionalRuleInfo[]
    - `id` string, required — Conditional rule ID
    - `target_id` string, required — api_id of the field that owns the rule, or the external_id of a checkbox group when the rule is owned by a group (groups have no api_id)
    - `action_type` 'show' | 'hide' | 'require', required — Action applied to action_field_ids when the conditions are met
    - `action_field_ids` string[] — api_ids of fields the rule affects when triggered
    - `conditions` object[]
      - `condition_type` 'any_of' | 'all_of' | 'none_of' | 'not_all_of' — How field_api_ids combine within this condition
      - `status` 'completed' | 'not_completed' — Field state that satisfies this condition
      - `join_operator` 'and_operator' | 'or_operator' — How this condition joins with the next one in the rule
      - `field_api_ids` string[] — api_ids of fields evaluated by this condition
      - `position` integer — Order of this condition within the rule

## Other responses

- `400` — bad request
- `422` — unprocessable entity
- `429` — rate limit exceeded

---

[API](https://skmtc.net/signwell/apis/signwell-developer-api.md) · [All operations](https://skmtc.net/signwell/apis/signwell-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signwell/signwell-developer-api/revisions/debef5796b62/schema)