DocSpring PDF Submissions API
The PDF Submissions API from DocSpring — 4 operation(s) for pdf submissions.
OpenAPI Specification
openapi: 3.0.3
info:
title: DocSpring Authentication PDF Submissions 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: PDF Submissions
paths:
/templates/{template_id}/submissions:
post:
operationId: generatePdf
summary: Generate a PDF
tags:
- PDF Submissions
responses:
'201':
description: submission created
content:
application/json:
schema:
type: object
title: create_submission_response
properties:
status:
type: string
enum:
- success
- error
submission:
$ref: '#/components/schemas/submission_preview'
errors:
type: array
items:
type: string
required:
- status
- submission
additionalProperties: false
example:
status: success
submission:
batch_id: null
data_requests:
- id: drq_1234567890abcdef01
email: jsmith@example.com
name: null
order: 0
sort_order: 0
fields: null
metadata: {}
state: pending
viewed_at: null
completed_at: null
data: null
auth_type: email_link
auth_second_factor_type: none
auth_provider: null
auth_session_started_at: null
auth_session_id_hash: null
auth_user_id_hash: null
auth_username_hash: null
auth_phone_number_hash: null
ip_address: null
user_agent: null
editable: null
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef01
json_schema_errors: []
metadata:
foo: 123
bar: baz
password: null
processed_at: null
state: waiting_for_data_requests
template_id: tpl_1234567890abcdef02
template_type: pdf
template_version: null
test: false
truncated_text: {}
pdf_hash: null
download_url: null
permanent_download_url: null
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
'422':
description: invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/submission_422_response'
type: object
title: create_submission_response
properties:
status:
type: string
enum:
- success
- error
submission:
$ref: '#/definitions/submission_preview'
errors:
type: array
items:
type: string
required:
- status
- submission
additionalProperties: false
example:
status: error
error: 'Invalid field_overrides. Fields do not exist for this template: ''non_existent'''
submission:
batch_id: null
data_requests: []
editable: null
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef01
json_schema_errors:
- The object did not contain a required property of 'last_name'
metadata:
foo: 123
bar: baz
password: null
processed_at: null
state: invalid_data
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: false
truncated_text: {}
pdf_hash: null
download_url: null
permanent_download_url: null
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
errors:
- The object did not contain a required property of 'last_name'
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Invalid API token secret
description: 'Creates a PDF submission by filling in a template with data. Supports both synchronous (default) and
asynchronous processing. Set `wait: false` to return immediately.
See also:
- [Customize the PDF Title and Filename](https://docspring.com/docs/api-guide/generate-pdfs/customize-pdf-title-and-filename/) - Set custom metadata
- [Handling Truncated Text](https://docspring.com/docs/api-guide/generate-pdfs/handle-truncated-text/) - Handle text that doesn''t fit in fields
'
externalDocs:
url: https://docspring.com/docs/api-guide/generate-pdfs/generate-pdfs-via-api/
description: Complete guide to generating PDFs with DocSpring
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef01
- name: wait
in: query
type: boolean
default: true
required: false
description: 'Wait for submission to be processed before returning. Set to false to return immediately. Default: true (on sync.* subdomain)'
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
data:
title: submission_data
type: object
data_requests:
items:
properties:
auth_phone_number_hash:
type:
- string
- 'null'
auth_provider:
type:
- string
- 'null'
auth_second_factor_type:
enum:
- none
- phone_number
- totp
- mobile_push
- security_key
- fingerprint
type: string
auth_session_id_hash:
type:
- string
- 'null'
auth_session_started_at:
type:
- string
- 'null'
auth_type:
enum:
- none
- password
- oauth
- email_link
- phone_number
- ldap
- saml
type: string
auth_user_id_hash:
type:
- string
- 'null'
auth_username_hash:
type:
- string
- 'null'
email:
type:
- string
- 'null'
fields:
items:
type:
- string
- 'null'
type: array
metadata:
type: object
name:
type:
- string
- 'null'
order:
type: integer
skipped:
type:
- boolean
- 'null'
title: create_submission_data_request_data
type:
- object
- 'null'
type: array
editable:
type: boolean
expires_in:
type: integer
field_overrides:
title: submission_field_overrides
type: object
metadata:
title: submission_metadata
type: object
password:
type: string
test:
type: boolean
version:
type: string
required:
- data
title: create_pdf_submission_data
type: object
example:
version: draft
data:
first_name: John
last_name: Smith
phone_number: '+11234567890'
metadata:
foo: 123
bar: baz
expires_in: 300
required: true
security:
- basicAuth: []
get:
operationId: listTemplateSubmissions
summary: List all submissions for a given template
tags:
- PDF Submissions
responses:
'200':
description: listing submissions
content:
application/json:
schema:
title: list_submissions_response
type: object
properties:
submissions:
type: array
items:
$ref: '#/components/schemas/submission'
limit:
type: integer
next_cursor:
type: string
nullable: true
required:
- submissions
- limit
- next_cursor
additionalProperties: false
example:
submissions:
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef11
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef02
template_type: pdf
template_version: null
test: false
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef11/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef12
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef02
template_type: pdf
template_version: null
test: false
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef12/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef13
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef02
template_type: pdf
template_version: null
test: false
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef13/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef14
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef02
template_type: pdf
template_version: null
test: false
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef14/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
next_cursor: sub_1234567890abcdef14
limit: 50
'404':
description: invalid template id
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
description: 'Returns a paginated list of all submissions for a specific template. Can be filtered by
date range, submission type (test/live), and optionally include submission data. Supports
cursor-based pagination for efficient retrieval of large result sets.
'
parameters:
- name: template_id
in: path
type: string
required: true
x-example: tpl_1234567890abcdef02
- name: cursor
in: query
type: string
required: false
- name: limit
in: query
type: integer
required: false
- name: created_after
in: query
type: string
required: false
- name: created_before
in: query
type: string
required: false
- name: type
in: query
type: string
required: false
- name: include_data
in: query
type: boolean
x-example: true
security:
- basicAuth: []
/submissions/{submission_id}:
get:
operationId: getSubmission
summary: Check the status of a PDF
tags:
- PDF Submissions
responses:
'200':
description: processed submission found with data
content:
application/json:
schema:
$ref: '#/components/schemas/submission'
example:
batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2018-10-27T13:00:00Z'
id: sub_1234567890abcdef01
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef01/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions:
- id: sba_1234567890abcdef01
integration_id: aci_1234567890abcdef01
state: processed
action_type: aws_s3_upload
action_category: file_upload
result_data:
s3_key: templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
s3_url: https://docspring-s3-example.s3.amazonaws.com/templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
s3_bucket: docspring-s3-example
s3_region: us-east-1
error_message: null
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
'404':
description: submission not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Submission 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 the details and status of a PDF submission. Returns processing state, download
URL (if processed), metadata, submission data (optional), and information about any
integrated actions. Use this to poll for completion when using asynchronous processing.
'
parameters:
- name: submission_id
in: path
type: string
required: true
x-example: sub_1234567890abcdef01
- name: include_data
in: query
type: boolean
x-example: true
security:
- basicAuth: []
delete:
operationId: expireSubmission
summary: Expire a PDF submission
tags:
- PDF Submissions
responses:
'200':
description: submission was expired
content:
application/json:
schema:
$ref: '#/components/schemas/submission_preview'
example:
batch_id: null
data_requests: []
editable: false
error_message: null
expired: true
expires_at: '2018-10-20T13:00:00Z'
id: sub_1234567890abcdef01
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: null
permanent_download_url: null
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions:
- id: sba_1234567890abcdef01
integration_id: aci_1234567890abcdef01
state: processed
action_type: aws_s3_upload
action_category: file_upload
result_data:
s3_key: templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
s3_url: https://docspring-s3-example.s3.amazonaws.com/templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
s3_bucket: docspring-s3-example
s3_region: us-east-1
error_message: null
'404':
description: submission not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Submission not found.
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Invalid API token secret
'403':
description: test API token used
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: You must use a live API token to expire a submission.
description: 'Expiring a PDF submission deletes the PDF and removes the data from our database.
This is useful for invalidating sensitive documents after they''ve been downloaded.
You can also [configure a data retention policy for your submissions](https://docspring.com/docs/template-editor/settings/#expire-submissions)
so that they automatically expire.
'
parameters:
- name: submission_id
in: path
type: string
required: true
x-example: sub_1234567890abcdef01
security:
- basicAuth: []
/submissions/{submission_id}/generate_preview:
post:
operationId: generatePreview
summary: Generate a preview PDF for partially completed data requests
tags:
- PDF Submissions
responses:
'200':
description: preview was successfully requested
content:
application/json:
schema:
$ref: '#/components/schemas/success_error_response'
example:
status: success
'404':
description: submission not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Submission not found.
'422':
description: error requesting preview
content:
application/json:
schema:
$ref: '#/components/schemas/success_error_response'
example:
status: error
error: Preview PDF cannot be generated when all data requests have been completed.
description: 'Generates a preview PDF for a submission with partially completed data requests. Useful
for showing users what the final document will look like before all signatures or data
have been collected. The preview includes any data collected so far.
'
parameters:
- name: submission_id
in: path
type: string
required: true
x-example: sub_1234567890abcdef01
security:
- basicAuth: []
/submissions:
get:
operationId: listSubmissions
summary: List all submissions
tags:
- PDF Submissions
responses:
'200':
description: listing submissions
content:
application/json:
schema:
title: list_submissions_response
type: object
properties:
submissions:
type: array
items:
$ref: '#/components/schemas/submission'
limit:
type: integer
next_cursor:
type: string
nullable: true
required:
- submissions
- limit
- next_cursor
additionalProperties: false
example:
submissions:
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef01
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef01/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef02
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef02/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
last_name: Smith
phone_number: '+11234567890'
- batch_id: null
data_requests: []
editable: false
error_message: null
expired: false
expires_at: '2020-10-27T13:00:00Z'
id: sub_1234567890abcdef03
json_schema_errors: []
metadata:
qux: abc
user_id: 42
password: null
processed_at: '2020-05-14T02:00:00Z'
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
truncated_text:
first_name:
- F. Scott Fitzgerald
pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
download_url: https://example.com/submissions/submission.pdf
permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef03/download
preview_download_url: null
preview_generated_at: null
audit_trail_download_url: null
actions: []
source: api
referrer: null
data:
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docspring/refs/heads/main/openapi/docspring-pdf-submissions-api-openapi.yml