SignWell Template API

openapi: 3.0.1
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:
    RateLimitErrorResponse:
      type: object
      description: Rate limit exceeded error response (HTTP 429)
      properties:
        error:
          type: string
          description: Rate limit error message indicating the limit and reset time
      required:
      - error
    AttachmentRequestInfo:
      type: object
      description: Attachment request information
      properties:
        name:
          type: string
          description: Name of the attachment request
        url:
          type: string
          format: url
          description: URL of the uploaded attachment (when available)
        required:
          type: boolean
          description: Whether the attachment is required
      required:
      - name
      - required
    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
    Placeholders:
      type: array
      description: 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.
      items:
        type: object
        properties:
          id:
            type: string
            description: 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:
            type: string
            description: Name of the placeholder.
          preassigned_recipient_name:
            type: string
            description: 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:
            type: string
            format: email
            description: 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.
        required:
        - id
        - name
    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.
        items:
          type: object
          properties:
            x:
              type: number
              format: float
              description: Horizontal value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located.
            y:
              type: number
              format: float
              description: Vertical value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located.
            page:
              type: integer
              description: The page number within the file. If the page does not exist within the file then the field won't be created.
            placeholder_id:
              type: string
              description: Unique identifier of the placeholder assigned to the field.
            type:
              $ref: '#/components/schemas/FieldType'
              description: 'Field type of the field. Valid field types: initials, signatures, checkbox, date, and text. To autofill fields with contact data, use an autofill field type. To group checkbox fields, enter an api_id for each checkbox and add the checkbox_groups parameter.'
            required:
              type: boolean
              default: true
              description: Whether the field must be completed by the recipient. Defaults to `true` except for checkbox type fields.
            label:
              type: string
              description: 'Text and Date fields only: label that is displayed when the field is empty.'
            value:
              on

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