SignWell Template API

openapi: 3.2.0
info:
  title: SignWell Developer API Application Template API
  description: API for creating, managing, and tracking electronic signature workflows.
  version: v1
  termsOfService: https://www.signwell.com/terms/
  contact:
    email: support@signwell.com
servers:
- url: https://www.signwell.com
tags:
- name: Template
  description: Create and manage reusable document templates.
paths:
  /api/v1/document_templates:
    get:
      summary: List Templates
      description: Returns a paginated list of templates for the authenticated account.
      tags:
      - Template
      security:
      - api_key: []
      operationId: listTemplates
      x-internal: true
      parameters:
      - name: page
        in: query
        schema:
          $ref: '#/components/schemas/Page'
        required: false
      - name: limit
        in: query
        schema:
          $ref: '#/components/schemas/Limit'
        required: false
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                templates:
                - id: bb3c3fba-116f-4b76-8ad8-5469c435f990
                  archived: false
                  created_at: '2026-03-31T15:47:00Z'
                  embedded_edit_url: https://www.signwell.com/edit/template/33f4447c-bdb2-4d3e-87b1-f57126549715/
                  language: en
                  name: miscarriage_branch/pariatur.tiff
                  requester_email_address: 53.tiny.rick@towne.example
                  status: Created
                  template_link: https://www.signwell.com/new_doc/y8cjPd25fuSHMBvi/
                  updated_at: '2026-03-31T15:47:00Z'
                  allow_decline: null
                  allow_reassign: null
                  api_application_id: null
                  decline_redirect_url: null
                  expires_in: null
                  redirect_url: null
                  reminders: null
                  metadata: null
                  fields: []
                  files: []
                  copied_placeholders: []
                  placeholders: []
                  checkbox_groups: []
                - id: 959e6f6a-8a95-47b1-9e86-eb8b1da5a8aa
                  archived: false
                  created_at: '2026-03-31T15:47:00Z'
                  embedded_edit_url: https://www.signwell.com/edit/template/d5f6572b-bcae-4c48-b187-540e577fb95a/
                  language: en
                  name: story_patience/eos.jpg
                  requester_email_address: 53.tiny.rick@towne.example
                  status: Created
                  template_link: https://www.signwell.com/new_doc/GfCKlbdBrLhLsHtX/
                  updated_at: '2026-03-31T15:47:00Z'
                  allow_decline: null
                  allow_reassign: null
                  api_application_id: null
                  decline_redirect_url: null
                  expires_in: null
                  redirect_url: null
                  reminders: null
                  metadata: null
                  fields: []
                  files: []
                  copied_placeholders: []
                  placeholders: []
                  checkbox_groups: []
                - id: 2038bbde-3423-43b1-991b-89e93a679511
                  archived: false
                  created_at: '2026-03-31T15:47:00Z'
                  embedded_edit_url: https://www.signwell.com/edit/template/e15e7107-498a-49c7-a5b2-4b0815744da1/
                  language: en
                  name: book-notebook/iure.mov
                  requester_email_address: 53.tiny.rick@towne.example
                  status: Created
                  template_link: https://www.signwell.com/new_doc/Qz2nb9ZeTqpsoBId/
                  updated_at: '2026-03-31T15:47:00Z'
                  allow_decline: null
                  allow_reassign: null
                  api_application_id: null
                  decline_redirect_url: null
                  expires_in: null
                  redirect_url: null
                  reminders: null
                  metadata: null
                  fields: []
                  files: []
                  copied_placeholders: []
                  placeholders: []
                  checkbox_groups: []
                current_page: 1
                next_page: null
                previous_page: null
                total_count: 3
                total_pages: 1
              schema:
                $ref: '#/components/schemas/DocumentTemplateListResponse'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                message: Missing or invalid authorization key
                meta:
                  error: api_key_unauthorized_error
                  message: Not valid authorization token
                  messages:
                  - Not valid authorization token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
    post:
      summary: Create Template
      description: Creates a new template.
      tags:
      - Template
      security:
      - api_key: []
      operationId: createTemplate
      parameters: []
      responses:
        '201':
          description: created
          content:
            application/json:
              example:
                id: 751f9aae-cb96-4fbe-805b-0135232823c4
                archived: false
                created_at: '2026-03-31T15:47:02Z'
                embedded_edit_url: https://www.signwell.com/edit/template/4fe3455d-6434-429f-bcd5-521c76f660f9/
                language: en
                name: Agreement
                requester_email_address: loggins_76@howe-hessel.test
                status: Created
                template_link: https://www.signwell.com/new_doc/c60LSiR31AhpOqZN/
                updated_at: '2026-03-31T15:47:02Z'
                allow_decline: true
                allow_reassign: null
                api_application_id: null
                decline_redirect_url: https://www.domain.com/decline_path/
                expires_in: 365
                redirect_url: https://www.domain.com/redirect_path/
                reminders: true
                metadata:
                  key1: value1
                  key2: value2
                apply_signing_order: false
                message: Normal Body
                subject: Normal subject
                labels:
                - id: 7409f919-0ad1-4b58-90b6-293177798f0a
                  name: My First Label
                - id: eff4718b-56b2-47e8-9ffa-8b4420937169
                  name: My Second Label
                - id: 29039f21-4b22-44d1-8dfa-5ee0696c7040
                  name: My Third Label
                fields:
                - - api_id: DateField_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: date
                    value: 2021/05/06
                    width: '86.0'
                    x: 230.0
                    y: 60.0
                    date_format: YYYY/MM/DD
                    formula: ''
                    lock_sign_date: true
                    placeholder_name: Placeholder One
                - - api_id: Signature_2
                    height: '32.0'
                    page: 1
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 260.0
                    y: 80.0
                    placeholder_name: Placeholder 2
                  - api_id: CheckBox_3
                    height: '13.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: t
                    width: '13.0'
                    x: 260.0
                    y: 80.0
                    name: null
                    placeholder_name: Placeholder 2
                  - api_id: CheckBox_4
                    height: '13.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: t
                    width: '13.0'
                    x: 270.0
                    y: 80.0
                    name: null
                    placeholder_name: Placeholder 2
                  - api_id: Initials_4
                    height: '32.0'
                    page: 1
                    required: true
                    type: initials
                    value: null
                    width: '44.0'
                    x: 260.0
                    y: 80.0
                    placeholder_name: Placeholder 2
                  - api_id: TextField_5
                    height: '19.0'
                    page: 1
                    required: true
                    type: text
                    value: '1'
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    fixed_width: true
                    label: label
                    validation: numbers
                    placeholder_name: Placeholder 2
                files:
                - name: filename1.pdf
                  pages_number: 0
                - name: filename2.pdf
                  pages_number: 0
                copied_placeholders:
                - id: '1'
                  name: Copied Placeholder 1
                  subject: null
                  message: null
                - id: '2'
                  name: Copied Placeholder 2
                  subject: null
                  message: null
                  preassigned_recipient_name: Nelson Copied 2
                  preassigned_recipient_email: nelson+copied2@docsketch.com
                placeholders:
                - id: placeholder_id_1
                  name: Placeholder One
                  subject: null
                  message: null
                  preassigned_recipient_name: recipient 1
                  preassigned_recipient_email: recipient1@domain.com
                  signing_order: 1
                  attachment_requests:
                  - name: normal name
                    required: true
                    url: https://www.signwell.com/document_attachments/GRJPOMRKppHWdGeeXwbefy4EblMb/?access=fa3580f5-3914-447b-8b4c-c5c28b0bc8f2
                - id: placeholder_id_2
                  name: Placeholder 2
                  subject: null
                  message: null
                  signing_order: 2
                  attachment_requests:
                  - name: Driver License
                    required: false
                    url: https://www.signwell.com/document_attachments/LRlW8OWw3pUGzP0jqa7Oi8kwJPY/?access=fa3580f5-3914-447b-8b4c-c5c28b0bc8f2
                checkbox_groups:
                - id: 076c3f53-a7a3-4dfa-820b-22cd9c66382a
                  group_name: Group 1
                  recipient_id: null
                  checkbox_ids:
                  - CheckBox_3
                  - CheckBox_4
                  validation: minimum
                  required: true
                  min_value: 1
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '400':
          description: bad request
          content:
            application/json:
              example:
                errors:
                  message: The request contains invalid key values.
                  invalid_keys:
                  - name
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '422':
          description: unprocessable entity
          content:
            application/json:
              example:
                errors:
                  decline_redirect_url:
                  - is not a valid URL
                  redirect_url:
                  - is not a valid URL
                  expires_in:
                  - must be less than or equal to 365
                  metadata:
                  - The key/value pairs must not exceed 50
                  - 'Check the following keys: [qgtxtpsnyxjwzvbzhnmrjziscxsmgcugpqanuygve], length needs to be less than 40 characters'
                  - 'Check the value of the following keys: [ke50], length needs to be less than 500 characters and must be a string'
                  api_application_id:
                  - The provided API application id is invalid
                  message:
                  - is too long (maximum is 4000 characters)
                  placeholders:
                    duplicated_ids: 'These ids are duplicated: placeholder_id_1.'
                    placeholder_1:
                      name:
                      - is too long (maximum is 255 characters)
                      preassigned_recipient_email:
                      - format is invalid.
                      preassigned_recipient_name:
                      - is too long (maximum is 255 characters)
                    placeholder_2:
                      preassigned_recipient_email:
                      - format is invalid.
                    all_preassigned: At least one placeholder should be left unassigned
                  attachment_requests:
                    invalid_ids: 'These placeholder ids are not present in the placeholders array: [placeholder_id_3]'
                  fields:
                    duplicated_api_ids: 'These api ids are duplicated: CheckBox_2.'
                    invalid_ids: 'These placeholder ids are not present in the placeholders array: [placeholder_id_2, placeholder_id_3]'
                    file_2:
                      field_2:
                        invalid_date_value: DateField value must be in Iso8601 format.
                        date_format:
                        - 'Allowed formats for date fields are: MM/DD/YYYY | DD/MM/YYYY | YYYY/MM/DD | Month DD, YYYY | MM/DD/YYYY hh:mm:ss a'
                  files:
                    file_1:
                      file_data:
                      - At least one of file_url or file_base64 should be present
                    file_2:
                      file_data:
                      - Only one of file_url or file_base64 should be present, not both
                    file_3:
                      file_url:
                      - is not a valid URL
                    file_4:
                      file_base64:
                      - 'the file type is unsupported, we support the following formats: application/msword, application/pdf, application/octet-stream, application/x-ole-storage, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/x-iwork-keynote-sffkey, application/x-iwork-numbers-sffnumbers, application/x-iwork-pages-sffpages, image/jpeg, image/png, image/tiff, image/webp, text/html'
                    file_5:
                      name:
                      - The file extension is invalid.
                    file_6:
                      name:
                      - can't be blank
                  checkbox_groups:
                    min_value_negative: The min value must be greater than or equal to 0 in the checkbox group Group 1
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateRequest'
        required: true
  /api/v1/document_templates/{id}:
    get:
      summary: Get Template
      description: Returns a template and all associated template data. Supply the unique template ID from either a Create Template request or template page URL.
      tags:
      - Template
      security:
      - api_key: []
      operationId: getTemplate
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/TemplateId'
        required: true
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 65564a6f-5582-4a3a-ada7-43ec1ceda89f
                archived: false
                created_at: '2026-03-31T15:47:00Z'
                embedded_edit_url: https://www.signwell.com/edit/template/ce591363-26ef-4e28-9261-4fb74ec9fca3/
                language: en
                name: conglomerate-glow/sint.mp4
                requester_email_address: 54.birdperson@oberbrunner.test
                status: Available
                template_link: https://www.signwell.com/new_doc/04G5HrgwsXPPHFQv/
                updated_at: '2026-03-31T15:47:00Z'
                allow_decline: null
                allow_reassign: null
                api_application_id: null
                decline_redirect_url: null
                expires_in: null
                redirect_url: null
                reminders: null
                metadata: null
                apply_signing_order: false
                message: Consequatur possimus delectus officia.
                subject: aut
                fields:
                - - api_id: Signature_43
                    height: '32.0'
                    page: 1
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 1.1
                    y: 1.1
                    placeholder_name: Dark Blob Girl 1
                  - api_id: Signature_44
                    height: '32.0'
                    page: 2
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 1.1
                    y: 1.1
                    placeholder_name: Doctor Falcon Strange 2
                files:
                - name: cum.flac
                  pages_number: 2
                copied_placeholders:
                - id: '3'
                  name: Penguin Iii 3
                  subject: null
                  message: null
                - id: '4'
                  name: Red Monarch Skull 4
                  subject: null
                  message: null
                  preassigned_recipient_name: Audrie Romaguera
                  preassigned_recipient_email: freeman.doyle@kreiger-mclaughlin.example
                placeholders:
                - id: '1'
                  name: Dark Blob Girl 1
                  subject: null
                  message: null
                  preassigned_recipient_name: Chung Gerlach
                  preassigned_recipient_email: danyell_toy@hudson.example
                  signing_order: 1
                  attachment_requests:
                  - name: distant_general/totam.xls
                    required: true
                    url: https://www.signwell.com/document_attachments/LG3l69ld2pIRQygpJK8oH56qQYp/?access=49fa240b-cb8b-48e0-ba0e-eda8808457d8
                - id: '2'
                  name: Doctor Falcon Strange 2
                  subject: null
                  message: null
                  signing_order: 2
                  attachment_requests: []
                checkbox_groups:
                - id: 48cae2b3-c81d-4e53-a91c-b70def9c01af
                  group_name: null
                  recipient_id: null
                  checkbox_ids:
                  - CheckBox_45
                  validation: null
                  required: false
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '404':
          description: not_found
          content:
            application/json:
              example:
                message: Not found
                meta:
                  error: record_not_found
                  message: Couldn't find the template requested
                  messages:
                  - Couldn't find the template requested
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
    put:
      summary: Update Template
      description: Updates an existing template.
      tags:
      - Template
      security:
      - api_key: []
      operationId: updateTemplate
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/TemplateId'
        required: true
      responses:
        '200':
          description: ok
          content:
            application/json:
              example:
                id: 2316597f-56b6-433f-a4a1-8f6356b2a5a5
                archived: false
                created_at: '2026-03-31T15:47:03Z'
                embedded_edit_url: https://www.signwell.com/edit/template/abbd8d88-9dfe-4a7f-9309-38cc7094a26d/
                language: en
                name: Broly
                requester_email_address: michael_79_jan_vincent@murray-lockman.example
                status: Available
                template_link: https://www.signwell.com/new_doc/5p8G0m8DiJ0XwNWB/
                updated_at: '2026-03-31T15:47:04Z'
                allow_decline: true
                allow_reassign: true
                api_application_id: cc86d352-f069-44e7-b23f-9a759209e2cd
                decline_redirect_url: http://weissnat.example/holly
                expires_in: 1
                redirect_url: http://williamson.example/patricia.pfeffer
                reminders: true
                metadata:
                  some: metadata
                apply_signing_order: true
                message: Nisi blanditiis aut ut.
                subject: Rem recusandae placeat ut.
                fields:
                - - api_id: Signature_55
                    height: '32.0'
                    page: 1
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 1.1
                    y: 1.1
                    placeholder_name: Blink Ix 13
                  - api_id: Signature_56
                    height: '32.0'
                    page: 2
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 1.1
                    y: 1.1
                    placeholder_name: Arclight 14
                files:
                - name: sunt.pptx
                  pages_number: 2
                copied_placeholders:
                - id: '3'
                  name: Bloodwraith 15
                  subject: null
                  message: null
                - id: '4'
                  name: Banshee 16
                  subject: null
                  message: null
                  preassigned_recipient_name: Rev. Sammy Wiza
                  preassigned_recipient_email: marcus@von.test
                placeholders:
                - id: '1'
                  name: Blink Ix 13
                  subject: null
                  message: null
                  preassigned_recipient_name: Mikaela Legros
                  preassigned_recipient_email: dexter.hintz@dicki-oberbrunner.example
                  signing_order: 1
                  attachment_requests:
                  - name: fruit-linger/non.js
                    required: true
                    url: https://www.signwell.com/document_attachments/5BO4O8z6DDHOqJ04on5OFzAa0e8/?access=ebfcdb81-ce6f-4e6e-b5eb-73495c0691c2
                - id: '2'
                  name: Arclight 14
                  subject: null
                  message: null
                  signing_order: 2
                  attachment_requests: []
                checkbox_groups:
                - id: b5b92745-c30e-462a-80bb-60ae8dab9b2b
                  group_name: null
                  recipient_id: null
                  checkbox_ids:
                  - CheckBox_57
                  validation: null
                  required: false
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '400':
          description: bad request
          content:
            application/json:
              example:
                errors:
                  message: The request contains invalid key values.
                  invalid_keys:
                  - name
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '422':
          description: unprocessable entity
          content:
            application/json:
              example:
                errors:
                  decline_redirect_url:
                  - is not a valid URL
                  redirect_url:
                  - is not a valid URL
                  expires_in:
                  - must be less than or equal to 365
                  metadata:
                  - The key/value pairs must not exceed 50
                  - 'Check the following keys: [qgtxtpsnyxjwzvbzhnmrjziscxsmgcugpqanuygve], length needs to be less than 40 characters'
                  - 'Check the value of the following keys: [ke50], length needs to be less than 500 characters and must be a string'
                  api_application_id:
                  - The provided API application id is invalid
                  message:
                  - is too long (maximum is 4000 characters)
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateUpdateRequest'
        required: true
    delete:
      summary: Delete Template
      description: Deletes a template. Supply the unique template ID from either a Create Template request or template page URL.
      tags:
      - Template
      security:
      - api_key: []
      operationId: deleteTemplate
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/TemplateId'
        required: true
      responses:
        '204':
          description: no content
        '404':
          description: not found
          content:
            application/json:
              example:
                message: Not found
                meta:
                  error: record_not_found
                  message: Couldn't find the template requested
                  messages:
                  - Couldn't find the template requested
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
components:
  schemas:
    Page:
      type: integer
      minimum: 1
      default: 1
      description: The page number for pagination. Defaults to the first page.
    DocumentTemplateUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the template.
        subject:
          type: string
          description: 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:
          type: string
          description: 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).
        draft:
          type: boolean
          default: false
          description: 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:
          type: integer
          minimum: 1
          description: 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:
          type: boolean
          default: true
          description: 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:
          type: boolean
          default: false
          description: When set to `true` recipients will sign one at a time in the order of the `recipients` collection of this request.
        api_application_id:
          type: string
          format: uuid
          description: 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
        redirect_url:
          type: string
          format: url
          description: A URL that recipients are redirected to after successfully signing a document.
        allow_decline:
          type: boolean
          default: true
          description: 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:
          type: boolean
          default: true
          description: 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:
          type: string
          format: url
          description: A URL that recipients are redirected to if the document is declined.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value data that can be associated with the document. If set, will be available every time the document data is returned.
        labels:
          $ref: '#/components/schemas/LabelsUpdate'
        checkbox_groups:
          $ref: '#/components/schemas/TemplateCheckboxGroups'
    Files:
      type: array
      description: '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'
      items:
        type: object
        properties:
          name:
            type: string
            description: Name of the file that will be uploaded.
          file_url:
            type: string
            format: url
            description: Publicly available URL of the file to be uploaded.
          file_base64:
            type: string
            format: byte
            description: A RFC 4648 base64 string of the file to be uploaded.
        required:
        - name
    FileInfo:
      type: object
      description: File information
      properties:
        name:
          type: string
          description: File name
        pages_number:
          type: integer
          description: Number of pages in the file
      required:
      - name
      - pages_number
    TemplateFields:
      type: array
      description: 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.
      items:
        type: array
        description: Array of Fields you're adding to each file.
        ite

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/signwell/refs/heads/main/openapi/signwell-template-api-openapi.yml