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:
              oneOf:
              - type: string
              - type: boolean
              - type: number
              description: 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.
            api_id:
              type: string
              description: Unique identifier of the field. Useful when needing to reference specific field values or update a document and its fields.
            name:
              type: string
              description: 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:
              $ref: '#/components/schemas/TextValidation'
              description: 'Text fields only: optional validation for field values. Valid values: numbers, letters, email_address, us_phone_number, us_zip_code, us_ssn, us_age, alphanumeric, us_bank_routing_number, us_bank_account.'
            fixed_width:
              type: boolean
              default: false
              description: '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:
              type: boolean
              default: false
              description: 'Date fields only: makes fields readonly and automatically populates with the date the recipient signed. Defaults to `false`.'
            date_format:
              $ref: '#/components/schemas/DateFormat'
              description: 'Date fields only: date format to use for the field. Valid values: MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD, Month DD, YYYY, and MM/DD/YYYY hh:mm:ss a. Defaults to MM/DD/YYYY.'
            height:
              type: number
              format: float
              description: '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:
              type: number
              format: float
              description: Width of the field (in pixels). For text fields, width will auto-grow unless `fixed_width` is true.
            options:
              type: array
              description: Array of dropdown options (for dropdown/select fields only)
              items:
                $ref: '#/components/schemas/DropdownOption'
            default_option:
              type: string
              description: Default selected option (for dropdown/select fields only)
            allow_other:
              type: boolean
              description: Whether to allow "Other" option with text input (for dropdown/select fields only)
              default: false
          required:
          - x
          - y
          - page
          - placeholder_id
          - type
    Page:
      type: integer
      minimum: 1
      default: 1
      description: The page number for pagination. Defaults to the first page.
    TemplateAttachmentRequests:
      type: array
      description: Attachments that a recipient must upload to complete the signing process. Attachment requests are shown after all document fields have been completed.
      items:
        type: object
        properties:
          name:
            type: string
            description: Name of the requested attachment.
          placeholder_id:
            type: string
            description: Unique identifier of the recipient that will view the attachment request.
          required:
            type: boolean
            default: true
            description: Whether the recipient will need to upload the attachment to successfully complete/sign the document. Defaults to `true`.
        required:
        - name
        - placeholder_id
    Limit:
      type: integer
      minimum: 1
      maximum: 50
      default: 10
      description: The number of documents to fetch. Defaults to 10, max is 50.
    CheckboxValidation:
      type: string
      enum:
      - minimum
      - maximum
      - range
      - exact
      description: Validation rule for checkbox groups
    TextValidation:
      type: string
      enum:
      - 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
      description: Validation rule for text fields
    Labels:
      type: array
      description: 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.
      items:
        $ref: '#/components/schemas/LabelRequest'
    LabelInfo:
      type: object
      description: Label information
      properties:
        id:
          type: string
          description: Label ID
        name:
          type: string
          description: Label name
    LabelsUpdate:
      type: array
      description: 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.
      items:
        $ref: '#/components/schemas/LabelRequest'
    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'
    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
    TemplateId:
      type: string
      format: uuid
      description: Unique identifier for a template.
    LabelRequest:
      type: object
      description: Labels can be used to organize documents and templates in a way that can make it easy to find using the document search/template search in SignWell. Labels can be used to organize documents in a way that can make it easy to find using the document search in SignWell.
      properties:
        name:
          type: string
      required:
      - name
    CopiedPlaceholders:
      type: array
      description: Copied placeholders are emailed the final document once it has been completed by all recipients.
      items:
        type: object
        properties:
          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:
        - name
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        message:
          type: string
          description: Human-readable error message
        meta:
          type: object
          properties:
            error:
              type: string
              description: Error code identifier
            message:
              type: string
              description: Detailed error message
            messages:
              type: array
              items:
                type: string
              description: List of error messages
          required:
          - error
          - message
    DocumentTemplateListResponse:
      type: object
      description: List of templates with pagination
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/DocumentTemplateResponse'
        current_page:
          type: integer
        next_page:
          type: integer
          nullable: true
        previous_page:
          type: integer
          nullable: true
        total_count:
          type: integer
        total_pages:
          type: integer
      required:
      - templates
      - current_page
      - total_count
      - total_pages
    FieldType:
      type: string
      enum:
      - 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
      description: Type of signing field
    DropdownOption:
      oneOf:
      - type: string
        title: SimpleOption
        description: Simple string option
      - type: object
        title: DetailedOption
        description: Detailed option object
        properties:
          name:
            type: string
            description: Option display name
          api_id:
            type: string
            description: Unique identifier for the option
          is_other:
            type: boolean
            description: Whether this is the special "Other" option
            default: false
        required:
        - name
      description: A dropdown option - either a simple string or a detailed object with name and optional api_id
    DocumentTemplateResponse:
      type: object
      properties:
        id:
          type: string
        api_application_id:
          type: string
          format: uuid
          nullable: true
        requester_email_address:
          type: string
          format: email
        custom_requester_name:
          type: string
          nullable: true
        custom_requester_email:
          type: string
          format: email
          nullable: true
        name:
          type: string
        subject:
          type: string
        message:
          type: string
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        placeholders:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              subject:
                type: string
                nullable: true
              message:
                type: string
                nullable: true
              preassigned_recipient_name:
                type: string
              preassigned_recipient_email:
                type: string
              signing_order:
                type: integer
              attachment_requests:
                type: array
                items:
                  $ref: '#/components/schemas/AttachmentRequestInfo'
            required:
            - name
        copied_placeholders:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              placeholder_id:
                type: string
              name:
                type: string
              subject:
                type: string
                nullable: true
              message:
                type: string
                nullable: true
              preassigned_recipient_name:
                type: string
              preassigned_recipient_email:
                type: string
            required:
            - name
        status:
          type: string
        reminders:
          type: boolean
          nullable: true
        archived:
          type: boolean
        embedded_edit_url:
          type: string
          format: url
          nullable: true
        template_link:
          type: string
          format: url
        template_id:
          type: string
          nullable: true
        apply_signing_order:
          type: boolean
        redirect_url:
          type: string
          format: url
          nullable: true
        decline_redirect_url:
          type: string
          format: url
          nullable: true
        language:
          type: string
        expires_in:
          type: integer
          nullable: true
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileInfo'
        fields:
          type: array
          items:
            type: array
            items:
              type: object
              properties:
                x:
                  type: number
                  format: float
                y:
                  type: number
                  format: float
                page:
                  type: integer
                recipient:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                    name:
                      type: string
                  required:
                  - email
                  - name
                api_id:
                  type: string
                  format: uuid
                name:
                  type: string
                  nullable: true
                date_format:
                  $ref: '#/components/schemas/DateFormat'
                fixed_width:
                  type: boolean
                formula:
                  type: string
                label:
                  type: string
                lock_sign_date:
                  type: boolean
                required:
                  type: boolean
                type:
                  $ref: '#/components/schemas/FieldType'
                validation:
                  $ref: '#/components/schemas/TextValidation'
                value:
                  oneOf:
                  - type: string
                  - type: boolean
                  - type: number
                  nullable: true
                height:
                  type: string
                width:
                  type: string
                recipient_id:
                  type: string
                  nullable: true
                signing_elements_group_id:
                  type: string
                  format: uuid
                placeholder_name:
                  type: string
                options:
                  type: array
                  description: Dropdown options (for dropdown/select fields)
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      api_id:
                        type: string
                      is_other:
                        type: boolean
                default_option:
                  type: string
                  description: Default selected option
                allow_other:
                  type: boolean
                  description: Whether "Other" option is allowed
              required:
              - x
              - y
              - page
        allow_decline:
          type: boolean
          nullable: true
        allow_reassign:
          type: boolean
          nullable: true
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelInfo'
        checkbox_groups:
          type: array
          items:
            $ref: '#/components/schemas/CheckboxGroupInfo'
      required:
      - id
    TemplateCheckboxGroups:
      type: array
      description: 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.
      items:
        type: object
        properties:
          group_name:
            type: string
            description: A unique identifier for the checkbox group.
          placeholder_id:
            type: string
            description: The recipient ID associated with the checkbox group.
          checkbox_ids:
            type: array
            items:
              type: string
              description: A unique identifier for each checkbox in a group. ID must match the api_id of the checkbox field.
          validation:
            $ref: '#/components/schemas/CheckboxValidation'
            description: 'Set requirements for the group of one or multiple selections by the recipient. Defaults to minimum. Validation values: minimum, maximum, exact, range.'
          required:
            type: boolean
            default: false
            description: Whether the group must be completed by the recipient. Defaults to false.
          min_value:
            type: integer
            description: 'The minimum number of checkboxes that must be checked in the group. (Only for validation: minimum and range)'
          max_value:
            type: integer
            description: 'The maximum number of checkboxes that can be checked in the group. (Only for validation: maximum and range)'
          exact_value:
            type: integer
            description: 'The exact number of checkboxes that must be checked in the group. (Only for validation: exact)'
        required:
        - group_name
        - placeholder_id
        - checkbox_ids
    DocumentTemplateRequest:
      type: object
      properties:
        files:
          $ref: '#/components/schemas/Files'
        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).
        placeholders:
          $ref: '#/components/schemas/Placeholders'
        copied_placeholders:
          $ref: '#/components/schemas/CopiedPlaceholders'
        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
        text_tags:
          type: boolean
          default: false
          description: 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:
          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.
        language:
          type: string
          description: '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.'
        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.
        fields:
          $ref: '#/components/schemas/TemplateFields'
        attachment_requests:
          $ref: '#/components/schemas/TemplateAttachmentRequests'
        labels:
          $ref: '#/components/schemas/Labels'
        checkbox_groups:
          $ref: '#/components/schemas/TemplateCheckboxGroups'
      required:
      - files
      - placeholders
    CheckboxGroupInfo:
      type: object
      description: Checkbox group configuration
      properties:
        id:
          type: string
          format: uuid
          description: Checkbox group ID
        group_name:
          type: string
          nullable: true
          description: Name of the checkbox group
        recipient_id:
          type: string
          nullable: true
          description: Recipient ID associated with the group
        checkbox_ids:
          type: array
          items:
            type: string
          description: IDs of checkboxes in this group
        validation:
          $ref: '#/components/schemas/CheckboxValidation'
          nullable: true
        required:
          type: boolean
          description: Whether at least one checkbox must be checked
        min_value:
          type: integer
          description: Minimum number of checkboxes to check
        max_value:
          type: integer
          description: Maximum number of checkboxes to check
        exact_value:
          type: integer
          description: Exact number of checkboxes that must be checked
      required:
      - id
      - checkbox_ids
      - required
    ValidationErrorResponse:
      type: object
      description: Validation error response. The errors object contains field-specific error details with dynamic keys.
      properties:
        errors:
          type: object
          additionalProperties: true
          description: Field-specific validation errors. Keys are field names (e.g., recipients, fields, files). Values can be strings, arrays of strings, or nested objects with further field-specific errors.
      required:
      - errors
    DateFormat:
      type: string
      enum:
      - MM/DD/YYYY
      - DD/MM/YYYY
      - YYYY/MM/DD
      - Month DD, YYYY
      - MM/DD/YYYY hh:mm:ss a
      description: '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'
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Api-Key
      in: header