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