DocSpring Submission Batches API
The Submission Batches API from DocSpring — 2 operation(s) for submission batches.
OpenAPI Specification
openapi: 3.0.3
info:
title: DocSpring Authentication Submission Batches 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: Submission Batches
paths:
/submissions/batches:
post:
operationId: batchGeneratePdfs
summary: Generate multiple PDFs
tags:
- Submission Batches
responses:
'201':
description: submissions created
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
- error
error:
type: string
errors:
type: array
items:
type: string
submission_batch:
$ref: '#/components/schemas/submission_batch'
submissions:
type: array
items:
type: object
properties:
status:
type: string
enum:
- success
- error
- valid_but_not_saved
errors:
type: array
items:
type: string
submission:
$ref: '#/components/schemas/submission_preview'
additionalProperties: false
required:
- status
required:
- status
- submission_batch
- submissions
additionalProperties: false
example:
status: success
submission_batch:
id: sbb_1234567890abcdef01
state: pending
metadata:
job_id: 54321
processed_at: null
total_count: 2
pending_count: 2
error_count: 0
completion_percentage: 0
submissions:
- status: success
submission:
batch_id: sbb_1234567890abcdef01
data_requests: []
editable: null
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef01
json_schema_errors: []
metadata:
submission_number: 1
password: null
processed_at: null
state: pending
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: []
- status: success
submission:
batch_id: sbb_1234567890abcdef01
data_requests: []
editable: null
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef02
json_schema_errors: []
metadata:
submission_number: 2
password: null
processed_at: null
state: pending
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
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: []
'200':
description: some PDFs with invalid data
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
- error
error:
type: string
errors:
type: array
items:
type: string
submission_batch:
$ref: '#/components/schemas/submission_batch'
submissions:
type: array
items:
type: object
properties:
status:
type: string
enum:
- success
- error
- valid_but_not_saved
errors:
type: array
items:
type: string
submission:
$ref: '#/components/schemas/submission_preview'
additionalProperties: false
required:
- status
required:
- status
- submission_batch
- submissions
additionalProperties: false
example:
status: error
submission_batch:
id: sbb_1234567890abcdef01
state: error
metadata:
job_id: 54321
processed_at: null
total_count: 2
pending_count: 0
error_count: 1
completion_percentage: 100
submissions:
- status: valid_but_not_saved
errors: []
- status: error
submission:
batch_id: sbb_1234567890abcdef01
data_requests: []
editable: null
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef02
json_schema_errors:
- The object did not contain a required property of 'first_name'
metadata:
submission_number: 2
password: null
processed_at: null
state: invalid_data
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: true
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 'first_name'
'401':
description: authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Invalid API token secret
'422':
description: array of arrays
content:
application/json:
schema:
$ref: '#/components/schemas/error_or_multiple_errors_response'
example:
status: error
error: 'You can only generate up to 50 PDFs per batch request. You requested: 51'
errors:
- 'The property ''#/submissions/0'' of type array did not match the following type: object'
'400':
description: invalid JSON
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: 'There was a problem with the JSON you submitted: unexpected character at line 1, column 25 in ''{ "first_name": "John", last_name: "Smith" }'
description: 'Generates up to 50 PDFs in a single request. Each submission can use a different template
and data. Supports both synchronous (wait for all PDFs) and asynchronous processing. More
efficient than individual requests when creating multiple PDFs.
See also:
- [Batch and Combine PDFs](https://docspring.com/docs/api-guide/generate-pdfs/batch-generate-pdfs/) - Generate and merge PDFs in one request
'
externalDocs:
url: https://docspring.com/docs/api-guide/generate-pdfs/batch-generate-pdfs/
description: Learn more about generating multiple PDFs in batches
parameters:
- name: wait
in: query
type: boolean
default: true
required: false
description: 'Wait for submission batch to be processed before returning. Set to false to return immediately. Default: true (on sync.* subdomain)'
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
metadata:
type: object
submissions:
items:
additionalProperties: false
properties:
css:
type: string
data:
type: object
html:
type: string
metadata:
type: object
template_id:
type:
- string
- 'null'
template_version:
type:
- string
- 'null'
test:
type: boolean
title: submission_data_batch_request
type: object
type: array
template_id:
type:
- string
- 'null'
template_version:
type:
- string
- 'null'
test:
type: boolean
required:
- submissions
title: submission_batch_data
type: object
example:
metadata:
job_id: 54321
test: true
template_id: null
template_version: null
submissions:
- test: false
template_id: tpl_1234567890abcdef01
template_version: draft
data:
first_name: Johnny
last_name: Smith
metadata:
submission_number: 1
- template_id: tpl_1234567890abcdef01
template_version: latest
data:
first_name: Jane
last_name: Doe
metadata:
submission_number: 2
required: true
security:
- basicAuth: []
/submissions/batches/{submission_batch_id}:
get:
operationId: getSubmissionBatch
summary: Check the status of a submission batch job
tags:
- Submission Batches
responses:
'200':
description: processed submission batch found
content:
application/json:
schema:
$ref: '#/components/schemas/submission_batch_with_submissions'
example:
id: sbb_1234567890abcdef01
state: error
metadata:
qux: abc
processed_at: null
total_count: 10
pending_count: 1
error_count: 2
completion_percentage: 90
submissions:
- batch_id: sbb_1234567890abcdef01
data_requests: []
editable: false
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef01
json_schema_errors: []
metadata: {}
password: null
processed_at: null
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: false
truncated_text: {}
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: []
- batch_id: sbb_1234567890abcdef01
data_requests: []
editable: false
error_message: null
expired: false
expires_at: null
id: sub_1234567890abcdef02
json_schema_errors: []
metadata: {}
password: null
processed_at: null
state: processed
template_id: tpl_1234567890abcdef01
template_type: pdf
template_version: null
test: false
truncated_text: {}
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: []
'404':
description: submission batch not found
content:
application/json:
schema:
$ref: '#/components/schemas/error_response'
example:
status: error
error: Submission batch 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 status and results of a batch PDF generation job. Returns processing state,
completion statistics, and optionally includes all individual submission details. Use this
to poll for completion when using asynchronous batch processing.
'
parameters:
- name: submission_batch_id
in: path
type: string
required: true
x-example: sbb_1234567890abcdef01
- name: include_submissions
in: query
type: boolean
x-example: true
security:
- basicAuth: []
components:
schemas:
submission_data_request:
title: submission_data_request
type: object
properties:
id:
type: string
nullable: true
email:
type: string
nullable: true
name:
type: string
nullable: true
order:
type: integer
nullable: true
sort_order:
type: integer
fields:
type: array
items:
type: string
nullable: true
metadata:
type: object
nullable: true
state:
type: string
enum:
- pending
- completed
viewed_at:
type: string
nullable: true
completed_at:
type: string
nullable: true
data:
type: object
nullable: true
auth_type:
type: string
enum:
- none
- password
- oauth
- email_link
- phone_number
- ldap
- saml
auth_second_factor_type:
type: string
enum:
- none
- phone_number
- totp
- mobile_push
- security_key
- fingerprint
auth_provider:
type: string
nullable: true
auth_session_started_at:
type: string
nullable: true
auth_session_id_hash:
type: string
nullable: true
auth_user_id_hash:
type: string
nullable: true
auth_username_hash:
type: string
nullable: true
auth_phone_number_hash:
type: string
nullable: true
ip_address:
type: string
nullable: true
user_agent:
type: string
nullable: true
required:
- auth_phone_number_hash
- auth_provider
- auth_second_factor_type
- auth_session_id_hash
- auth_session_started_at
- auth_type
- auth_user_id_hash
- auth_username_hash
- completed_at
- data
- email
- fields
- id
- ip_address
- metadata
- name
- order
- sort_order
- state
- user_agent
- viewed_at
additionalProperties: false
submission_preview:
title: submission_preview
type: object
properties:
batch_id:
type: string
nullable: true
data_requests:
type: array
items:
$ref: '#/components/schemas/submission_data_request'
editable:
type: boolean
nullable: true
error_message:
type: string
nullable: true
expired:
type: boolean
expires_at:
type: string
nullable: true
id:
type: string
nullable: true
json_schema_errors:
type: array
items:
type: string
nullable: true
metadata:
type: object
password:
type: string
nullable: true
processed_at:
type: string
nullable: true
state:
type: string
enum:
- pending
- processed
- invalid_data
- error
- image_download_failed
- image_processing_failed
- waiting_for_data_requests
- syntax_error
- account_suspended
- license_revoked
- accidental
template_id:
type: string
nullable: true
template_type:
type: string
enum:
- pdf
- html
template_version:
type: string
nullable: true
test:
type: boolean
truncated_text:
type: object
nullable: true
pdf_hash:
type: string
nullable: true
download_url:
type: string
nullable: true
permanent_download_url:
type: string
nullable: true
preview_download_url:
type: string
nullable: true
preview_generated_at:
type: string
nullable: true
audit_trail_download_url:
type: string
nullable: true
actions:
type: array
items:
$ref: '#/components/schemas/submission_action'
required:
- actions
- audit_trail_download_url
- batch_id
- data_requests
- download_url
- editable
- error_message
- expired
- expires_at
- id
- json_schema_errors
- metadata
- password
- pdf_hash
- permanent_download_url
- preview_download_url
- preview_generated_at
- processed_at
- state
- template_id
- template_type
- template_version
- test
- truncated_text
additionalProperties: false
error_or_multiple_errors_response:
type: object
title: error_or_multiple_errors_response
properties:
status:
type: string
enum:
- error
error:
type: string
description: Single error message (when only one error occurred)
errors:
type: array
items:
type: string
description: Array of error messages (when multiple validation errors occurred)
required:
- status
additionalProperties: false
error_response:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
required:
- status
- error
additionalProperties: false
title: error_response
submission_action:
title: submission_action
type: object
properties:
id:
type: string
nullable: true
integration_id:
type: string
nullable: true
state:
type: string
enum:
- pending
- processed
- failed
- error
action_type:
type: string
enum:
- webhook
- slack_webhook
- email
- aws_s3_upload
action_category:
type: string
enum:
- notification
- file_upload
result_data:
type: object
error_message:
type: string
nullable: true
required:
- action_category
- action_type
- error_message
- id
- integration_id
- result_data
- state
additionalProperties: false
submission_batch_with_submissions:
title: submission_preview
type: object
properties:
id:
type: string
nullable: true
state:
type: string
enum:
- pending
- processed
- error
metadata:
type: object
processed_at:
type: string
nullable: true
total_count:
type: integer
pending_count:
type: integer
error_count:
type: integer
completion_percentage:
type: number
submissions:
type: array
items:
$ref: '#/components/schemas/submission_preview'
required:
- completion_percentage
- error_count
- id
- metadata
- pending_count
- processed_at
- state
- total_count
additionalProperties: false
submission_batch:
title: submission_batch
type: object
properties:
id:
type: string
nullable: true
state:
type: string
enum:
- pending
- processed
- error
metadata:
type: object
processed_at:
type: string
nullable: true
total_count:
type: integer
pending_count:
type: integer
error_count:
type: integer
completion_percentage:
type: number
required:
- completion_percentage
- error_count
- id
- metadata
- pending_count
- processed_at
- state
- total_count
additionalProperties: false
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Username: API Token ID, Password: API Token Secret'
externalDocs:
url: https://docspring.com/docs/
description: DocSpring API Documentation