DocSpring Templates API
The Templates API from DocSpring — 8 operation(s) for templates.
OpenAPI Specification
openapi: 3.0.3
info:
title: DocSpring Authentication Templates API
description: Use DocSpring's API to programmatically fill out PDF forms, convert HTML to PDFs, merge PDFs, or request legally binding e-signatures.
version: v1
contact:
url: https://docspring.com/docs/
license:
name: Proprietary
servers:
- url: https://sync.api.docspring.com/api/v1
description: DocSpring API
security:
- basicAuth: []
tags:
- name: Templates
paths:
/templates:
get:
operationId: listTemplates
summary: Get a list of all templates
tags:
- Templates
responses:
'200':
description: enumerate all templates
content:
application/json:
schema:
title: list_templates
type: array
items:
$ref: '#/components/schemas/template_preview'
additionalProperties: false
example:
- add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: test-document.pdf
document_md5: null
document_parse_error: false
document_processed: true
document_state: pending
document_url: https://docspring-s3-example.s3.amazonaws.com/store/templates/test/test-document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=docspring-s3-example%2F20210101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210101T090000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef0123456789
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: true
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: false
id: tpl_1234567890abcdef04
locked: false
merge_audit_trail_pdf: true
name: Sub Template 1
page_count: 3
page_dimensions:
- - 612
- 792
- - 792
- 612
- - 612
- 792
parent_folder_id: fld_1234567890abcdef01
path: /Folder
permanent_document_url: https://app.docspring.com/templates/tpl_1234567890abcdef04/original_pdf?token=123456789abcdef
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: pdf
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: null
last_changed_by_type: null
last_changed_by_id: null
- add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: null
document_md5: null
document_parse_error: false
document_processed: false
document_state: pending
document_url: null
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: true
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: false
id: tpl_1234567890abcdef03
locked: false
merge_audit_trail_pdf: true
name: Template 3
page_count: 1
page_dimensions: null
parent_folder_id: null
path: /
permanent_document_url: null
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: html
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: null
last_changed_by_type: null
last_changed_by_id: null
- add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: test-document.pdf
document_md5: null
document_parse_error: false
document_processed: true
document_state: pending
document_url: https://docspring-s3-example.s3.amazonaws.com/store/templates/test/test-document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=docspring-s3-example%2F20210101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210101T090000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef0123456789
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: true
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: false
id: tpl_1234567890abcdef02
locked: false
merge_audit_trail_pdf: true
name: Template 2
page_count: 3
page_dimensions:
- - 612
- 792
- - 792
- 612
- - 612
- 792
parent_folder_id: null
path: /
permanent_document_url: https://app.docspring.com/templates/tpl_1234567890abcdef02/original_pdf?token=123456789abcdef
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: pdf
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: null
last_changed_by_type: null
last_changed_by_id: null
- add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: blank_pdf.pdf
document_md5: 1c32d785398e3a7eaab0e9b876903cc6
document_parse_error: false
document_processed: true
document_state: processed
document_url: https://docspring-s3-example.s3.amazonaws.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=docspring-s3-example%2F20210101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210101T090000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef0123456789
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: true
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: false
id: tpl_1234567890abcdef01
locked: false
merge_audit_trail_pdf: true
name: Template 1
page_count: 1
page_dimensions:
- - 612
- 792
parent_folder_id: null
path: /
permanent_document_url: https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: pdf
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: null
last_changed_by_type: null
last_changed_by_id: null
'404':
description: filter templates by invalid folder id
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
description: 'Retrieves a list of your templates with search, filtering, and pagination options. Returns
basic template information including ID, name, type (PDF or HTML), and folder location.
Supports text search by name and filtering by parent folder.
'
parameters:
- name: query
in: query
type: string
required: false
description: Search By Name
x-example: '2'
- name: parent_folder_id
in: query
type: string
required: false
description: Filter By Folder Id
x-example: fld_1234567890abcdef01
- name: page
in: query
type: integer
minimum: 1
required: false
description: 'Default: 1'
x-example: 2
- name: per_page
in: query
type: integer
minimum: 1
maximum: 50
required: false
description: 'Default: 50'
x-example: 1
security:
- basicAuth: []
post:
operationId: createPdfTemplate
summary: Create a new PDF template with a form POST file upload
tags:
- Templates
responses:
'201':
description: returns a pending template
content:
application/json:
schema:
$ref: '#/components/schemas/template_preview'
example:
add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: fw8ben.pdf
document_md5: ca6fdfed355b9e89f9a94ee54688a231
document_parse_error: false
document_processed: false
document_state: pending
document_url: /cache/cached_upload.pdf
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: false
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: true
id: tpl_1234567890abcdef01
locked: false
merge_audit_trail_pdf: true
name: Test Template
page_count: 0
page_dimensions: null
parent_folder_id: fld_1234567890abcdef01
path: /Folder
permanent_document_url: null
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: pdf
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: '2018-10-20T09:00:00.000-04:00'
last_changed_by_type: null
last_changed_by_id: usr_1234567890abcdef01
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
description: 'Creates a new PDF template by uploading a PDF file. The uploaded PDF becomes the foundation
for your template, and you can then add fillable fields using the template editor. Use the
wait parameter to control whether the request waits for document processing to complete.
'
parameters:
- name: wait
in: query
type: boolean
default: true
required: false
description: 'Wait for template document to be processed before returning. Set to false to return immediately. Default: true (on sync.* subdomain)'
x-example: true
- name: template[document]
in: formData
type: file
required: true
x-example: <Uploaded File>
- name: template[name]
in: formData
type: string
required: true
x-example: Test Template
- name: template[description]
in: formData
type: string
required: false
- name: template[parent_folder_id]
in: formData
type: string
required: false
x-example: fld_1234567890abcdef01
security:
- basicAuth: []
/templates/{template_id}:
get:
operationId: getTemplate
summary: Check the status of an uploaded template
tags:
- Templates
responses:
'200':
description: template found
content:
application/json:
schema:
$ref: '#/components/schemas/template_preview'
example:
add_data_request_submission_id_footers: true
allow_additional_properties: false
description: null
document_filename: blank_pdf.pdf
document_md5: 1c32d785398e3a7eaab0e9b876903cc6
document_parse_error: false
document_processed: true
document_state: processed
document_url: https://docspring-s3-example.s3.amazonaws.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=docspring-s3-example%2F20210101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210101T090000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef0123456789
editable_submissions: false
embed_domains: null
encrypt_pdfs_password: null
encrypt_pdfs: false
expiration_interval: days
expire_after: 7
expire_submissions: true
external_predefined_fields_template_id: null
external_predefined_fields_template_name: null
first_template: false
id: tpl_1234567890abcdef01
locked: false
merge_audit_trail_pdf: true
name: Template 1
page_count: 1
page_dimensions:
- - 612
- 792
parent_folder_id: null
path: /
permanent_document_url: https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef
public_submissions: false
public_web_form: false
redirect_url: null
slack_webhook_url: null
template_type: pdf
updated_at: '2018-10-20T09:00:00.000-04:00'
version_published_at: null
version: null
webhook_url: null
demo: false
latest_version: null
last_changed_at: null
last_changed_by_type: null
last_changed_by_id: null
'404':
description: template not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Template not found
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
description: 'Retrieves information about a template including processing status and document URL.
Use this to check if template is ready to view in the template editor or generate PDFs.
'
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef01
security:
- basicAuth: []
put:
operationId: updateTemplate
summary: Update a Template
tags:
- Templates
responses:
'200':
description: update template success
content:
application/json:
schema:
$ref: '#/components/schemas/success_multiple_errors_response'
example:
status: success
description: 'Updates template content and properties. For HTML templates, you can modify the HTML,
SCSS, headers, footers, name, and description. Changes are applied to your draft
template and do not affect published template versions.
'
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef03
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
template:
additionalProperties: false
properties:
add_data_request_submission_id_footers:
type: boolean
allow_additional_properties:
type: boolean
defaults:
additionalProperties: false
properties:
alignment:
enum:
- left
- center
- right
type: string
backgroundColor:
type:
- string
- 'null'
bold:
type: boolean
characterSpacing:
type: number
checkBackgroundColor:
type:
- string
- 'null'
checkCharacter:
type:
- string
- 'null'
checkColor:
type:
- string
- 'null'
color:
type:
- string
- 'null'
dateFormat:
type:
- string
- 'null'
dateTimeFormat:
type:
- string
- 'null'
falseText:
type:
- string
- 'null'
fontSize:
type: number
opacity:
type: number
shapeBorderColor:
type:
- string
- 'null'
shapeBorderWidth:
type: number
shapeFillColor:
type:
- string
- 'null'
textColor:
type:
- string
- 'null'
trueText:
type:
- string
- 'null'
typeface:
type:
- string
- 'null'
uppercase:
type: boolean
required:
- color
- fontSize
- typeface
type: object
description:
type:
- string
- 'null'
editable_submissions:
type: boolean
embed_domains:
type:
- string
- 'null'
encrypt_pdfs:
type: boolean
encrypt_pdfs_password:
type:
- string
- 'null'
expiration_interval:
enum:
- minutes
- hours
- days
type: string
expire_after:
type: number
expire_submissions:
type: boolean
external_predefined_fields_template_id:
type:
- string
- 'null'
external_predefined_fields_template_name:
type:
- string
- 'null'
field_order:
items:
items:
type: number
type: array
type: array
fields:
type: object
fields_patch:
description: Array of field updates to apply
items:
type: object
type: array
footer_html:
type:
- string
- 'null'
header_html:
type:
- string
- 'null'
html:
type:
- string
- 'null'
html_engine_options:
type: object
locked:
type: boolean
merge_audit_trail_pdf:
type: boolean
name:
type:
- string
- 'null'
parent_folder_id:
type:
- string
- 'null'
predefined_fields:
items:
type: object
type: array
predefined_fields_sample_data:
description: Sample data for predefined fields. Can be a string when sent with multipart form upload.
type:
- object
- string
public_submissions:
type: boolean
public_web_form:
type: boolean
redirect_url:
type:
- string
- 'null'
scss:
type:
- string
- 'null'
shared_field_data:
type: object
shared_field_data_patch:
description: Array of shared field data updates to apply
items:
type: object
type: array
slack_webhook_url:
type:
- string
- 'null'
template_type:
enum:
- pdf
- html
type: string
webhook_options:
properties:
exclude_data:
type: boolean
type:
- object
- 'null'
webhook_url:
type:
- string
- 'null'
title: update_html_template_data
type: object
required:
- template
title: update_html_template
type: object
example:
template:
html: updated html
scss: updated scss
header_html: updated header
footer_html: updated footer
webhook_options:
exclude_data: true
required: true
security:
- basicAuth: []
delete:
operationId: deleteTemplate
summary: Delete a template
tags:
- Templates
responses:
'200':
description: template version deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/template_delete_response'
example:
status: success
latest_version: 1.0.1
versions:
- version: 1.0.1
description: null
published_at: '2018-10-20T09:00:02.000-04:00'
published_by_id: usr_1234567890abcdef01
- version: 1.0.0
description: null
published_at: '2018-10-20T09:00:01.000-04:00'
published_by_id: usr_1234567890abcdef01
'404':
description: template not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Template not found
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
description: 'Deletes a template or a specific template version. When no version is specified, deletes
the entire template including all versions. When a version is specified, deletes only
that version while preserving others. Returns remaining version information.
'
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef01
- name: version
in: query
type: string
required: false
x-example: 0.1.0
security:
- basicAuth: []
/templates/{template_id}/publish_version:
post:
operationId: publishTemplateVersion
summary: Publish a template version
tags:
- Templates
responses:
'200':
description: version published successfully
content:
application/json:
schema:
$ref: '#/components/schemas/template_publish_version_response'
example:
status: success
result:
version: 0.1.0
description: Added new fields
published_by_id: usr_1234567890abcdef01
published_at: '2018-10-20T09:00:00.000-04:00'
'422':
description: invalid version type
content:
application/json:
schema:
$ref: '#/components/schemas/success_multiple_errors_response'
example:
status: error
errors:
- 'Invalid version type! Must be one of: major, minor, patch'
'404':
description: template not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Template not found
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
description: 'Publishes the current draft version of a template and creates a new immutable version
with semantic versioning (major.minor.patch).
'
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef01
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
description:
type: string
version_type:
type: string
required:
- version_type
title: publish_version_data
type: object
example:
version_type: minor
description: Added new fields
required: true
security:
- basicAuth: []
/templates/{template_id}/restore_version:
post:
operationId: restoreTemplateVersion
summary: Restore a template version
tags:
- Templates
responses:
'200':
description: version restored successfully
content:
application/json:
schema:
$ref: '#/components/schemas/success_error_response'
example:
status: success
'422':
description: draft version not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/success_multiple_errors_response'
example:
status: error
errors:
- Version is required!
'404':
description: template version not found
content:
applicat
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docspring/refs/heads/main/openapi/docspring-templates-api-openapi.yml