Signature requests can be initiated with Submissions API. Submissions can contain one submitter if signed by a single party or multiple submitters if the document template form contains signatures and fields to be collected and filled by multiple parties. Initiate new submissions to request signatures for specified submitters via email or phone number.
openapi: 3.0.0
info:
version: 1.0.0
title: DocuSeal Submissions API
description: DocuSeal API specs
contact:
name: DocuSeal
email: admin@docuseal.com
url: https://www.docuseal.com
servers:
- url: https://api.docuseal.com
description: Global Server
- url: https://api.docuseal.eu
description: EU Server
tags:
- name: Submissions
description: Signature requests can be initiated with Submissions API. Submissions can contain one submitter if signed by a single party or multiple submitters if the document template form contains signatures and fields to be collected and filled by multiple parties. Initiate new submissions to request signatures for specified submitters via email or phone number.
paths:
/submissions:
get:
security:
- AuthToken: []
tags:
- Submissions
summary: List all submissions
description: The API endpoint provides the ability to retrieve a list of available submissions.
operationId: getSubmissions
parameters:
- name: template_id
in: query
required: false
schema:
type: integer
description: The template ID allows you to receive only the submissions created from that specific template.
- name: status
in: query
required: false
schema:
type: string
enum:
- pending
- completed
- declined
- expired
description: Filter submissions by status.
- name: q
in: query
required: false
schema:
type: string
description: Filter submissions based on submitter's name, email or phone partial match.
- name: slug
in: query
required: false
schema:
type: string
description: Filter submissions by unique slug.
example: NtLDQM7eJX2ZMd
- name: template_folder
in: query
required: false
schema:
type: string
description: Filter submissions by template folder name.
- name: archived
in: query
required: false
schema:
type: boolean
description: Returns only archived submissions when `true` and only active submissions when `false`.
- name: limit
in: query
required: false
schema:
type: integer
description: The number of submissions to return. Default value is 10. Maximum value is 100.
- name: after
in: query
required: false
schema:
type: integer
description: The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions.
- name: before
in: query
required: false
schema:
type: integer
description: The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
type: object
required:
- id
- source
- slug
- status
- submitters_order
- audit_log_url
- completed_at
- created_at
- updated_at
- submitters
- created_by_user
properties:
id:
type: integer
description: Submission unique ID number.
name:
type: string
description: Name of the document submission.
example: Test Submission Document
source:
type: string
description: The source of the submission.
enum:
- invite
- bulk
- api
- embed
- link
slug:
type: string
description: Unique slug of the submission.
status:
type: string
description: The status of the submission.
enum:
- completed
- declined
- expired
- pending
submitters_order:
type: string
description: The order of submitters.
enum:
- random
- preserved
audit_log_url:
type: string
nullable: true
description: Audit log file URL.
combined_document_url:
type: string
nullable: true
description: Combined PDF file URL with documents and Audit Log.
completed_at:
type: string
nullable: true
description: The date and time when the submission was completed.
created_at:
type: string
description: The date and time when the submission was created.
updated_at:
type: string
description: The date and time when the submission was last updated.
archived_at:
type: string
nullable: true
description: The date and time when the submission was archived.
submitters:
type: array
description: The list of submitters.
items:
type: object
required:
- id
- submission_id
- uuid
- email
- slug
- sent_at
- opened_at
- completed_at
- declined_at
- created_at
- updated_at
- name
- phone
- status
- role
- metadata
- preferences
properties:
id:
type: integer
description: Submitter unique ID number.
submission_id:
type: integer
description: Submission unique ID number.
uuid:
type: string
description: Submitter UUID.
email:
type: string
nullable: true
description: The email address of the submitter.
slug:
type: string
description: Unique key to be used in the form signing link and embedded form.
sent_at:
type: string
nullable: true
description: The date and time when the signing request was sent to the submitter.
opened_at:
type: string
nullable: true
description: The date and time when the submitter opened the signing form.
completed_at:
type: string
nullable: true
description: The date and time when the submitter completed the signing form.
declined_at:
type: string
nullable: true
description: The date and time when the submitter declined the signing form.
created_at:
type: string
description: The date and time when the submitter was created.
updated_at:
type: string
description: The date and time when the submitter was last updated.
name:
type: string
nullable: true
description: The name of the submitter.
phone:
type: string
nullable: true
description: The phone number of the submitter.
external_id:
type: string
nullable: true
description: Your application-specific unique string key to identify this submitter within your app.
status:
type: string
description: The status of signing request for the submitter.
enum:
- completed
- declined
- opened
- sent
- awaiting
role:
type: string
description: The role of the submitter in the signing process.
metadata:
type: object
description: Metadata object with additional submitter information.
preferences:
type: object
description: Submitter preferences.
template:
type: object
required:
- id
- name
- external_id
- folder_name
- created_at
- updated_at
properties:
id:
type: integer
description: Unique identifier of the document template.
name:
type: string
description: The name of the template.
external_id:
type: string
nullable: true
description: Your application-specific unique string key to identify this template within your app.
folder_name:
type: string
description: Folder name where the template is located.
created_at:
type: string
description: The date and time when the template was created.
updated_at:
type: string
description: The date and time when the template was last updated.
created_by_user:
type: object
nullable: true
required:
- id
- first_name
- last_name
- email
properties:
id:
type: integer
description: Unique identifier of the user who created the submission.
first_name:
type: string
description: The first name of the user who created the submission.
last_name:
type: string
description: The last name of the user who created the submission.
email:
type: string
description: The email address of the user who created the submission.
pagination:
type: object
required:
- count
- next
- prev
properties:
count:
type: integer
description: Submissions count.
next:
type: integer
nullable: true
description: The ID of the submission after which the next page starts.
prev:
type: integer
nullable: true
description: The ID of the submission before which the previous page ends.
example:
data:
- id: 1
name: null
source: link
submitters_order: random
slug: VyL4szTwYoSvXq
status: completed
audit_log_url: https://docuseal.com/file/hash/example.pdf
combined_document_url: null
expire_at: null
completed_at: '2023-12-10T15:49:21.895Z'
created_at: '2023-12-10T15:48:17.166Z'
updated_at: '2023-12-10T15:49:21.895Z'
archived_at: null
submitters:
- id: 1
submission_id: 1
uuid: 0954d146-db8c-4772-aafe-2effc7c0e0c0
email: submitter@example.com
slug: dsEeWrhRD8yDXT
sent_at: '2023-12-14T15:45:49.011Z'
opened_at: '2023-12-14T15:48:23.011Z'
completed_at: '2023-12-14T15:49:21.701Z'
declined_at: null
created_at: '2023-12-10T15:48:17.173Z'
updated_at: '2023-12-14T15:50:21.799Z'
name: John Doe
phone: '+1234567890'
status: completed
role: First Party
metadata: {}
preferences: {}
template:
id: 1
name: Example Template
external_id: Temp123
folder_name: Default
created_at: '2023-12-14T15:50:21.799Z'
updated_at: '2023-12-14T15:50:21.799Z'
created_by_user:
id: 1
first_name: Bob
last_name: Smith
email: bob.smith@example.com
pagination:
count: 1
next: 1
prev: 1
post:
security:
- AuthToken: []
tags:
- Submissions
summary: Create a submission
description: This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers).<br><b>Related Guides</b><br><a href="https://www.docuseal.com/guides/send-documents-for-signature-via-api" class="link">Send documents for signature via API</a><br><a href="https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api" class="link">Pre-fill PDF document form fields with API</a>
operationId: createSubmission
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- template_id
- submitters
properties:
template_id:
type: integer
description: The unique identifier of the template. Document template forms can be created via the Web UI, <a href="https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form" class="link">PDF and DOCX API</a>, or <a href="https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api" class="link">HTML API</a>.
example: 1000001
send_email:
type: boolean
description: Set `false` to disable signature request emails sending.
default: true
send_sms:
type: boolean
description: Set `true` to send signature request via phone number and SMS.
default: false
order:
type: string
description: Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.
default: preserved
enum:
- preserved
- random
completed_redirect_url:
type: string
description: Specify URL to redirect to after the submission completion.
bcc_completed:
type: string
description: Specify BCC address to send signed documents to after the completion.
reply_to:
type: string
description: Specify Reply-To address to use in the notification emails.
expire_at:
type: string
description: Specify the expiration date and time after which the submission becomes unavailable for signature.
example: 2024-09-01 12:00:00 UTC
variables:
type: object
description: Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in dynamic template documents.
example:
variable_name: value
message:
type: object
description: Custom signature request email message.
properties:
subject:
type: string
description: Custom signature request email subject.
body:
type: string
description: 'Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.'
submitters:
type: array
description: The list of submitters for the submission.
items:
type: object
properties:
name:
type: string
description: The name of the submitter.
role:
type: string
description: The role name or title of the submitter.
example: First Party
email:
type: string
description: The email address of the submitter.
format: email
example: john.doe@example.com
phone:
type: string
description: The phone number of the submitter, formatted according to the E.164 standard.
example: '+1234567890'
values:
type: object
description: An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param.
external_id:
type: string
description: Your application-specific unique string key to identify this submitter within your app.
completed:
type: boolean
description: Pass `true` to mark submitter as completed and auto-signed via API.
metadata:
type: object
description: Metadata object with additional submitter information.
example: '{ "customField": "value" }'
send_email:
type: boolean
description: Set `false` to disable signature request emails sending only for this submitter.
default: true
send_sms:
type: boolean
description: Set `true` to send signature request via phone number and SMS.
default: false
reply_to:
type: string
description: Specify Reply-To address to use in the notification emails for this submitter.
completed_redirect_url:
type: string
description: Submitter specific URL to redirect to after the submission completion.
order:
type: integer
description: The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array.
require_phone_2fa:
type: boolean
description: Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.
default: false
require_email_2fa:
type: boolean
description: Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.
default: false
message:
type: object
description: Custom signature request email message for the submitter.
properties:
subject:
type: string
description: Custom signature request email subject for the submitter.
body:
type: string
description: 'Custom signature request email body for the submitter. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.'
fields:
type: array
description: A list of configurations for template document form fields.
items:
type: object
required:
- name
properties:
name:
type: string
description: Document template field name.
example: First Name
default_value:
oneOf:
- type: string
- type: number
- type: boolean
- type: array
items:
oneOf:
- type: string
- type: number
- type: boolean
description: Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.
example: Acme
readonly:
type: boolean
description: Set `true` to make it impossible for the submitter to edit predefined field value.
default: false
required:
type: boolean
description: Set `true` to make the field required.
title:
type: string
description: Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
description:
type: string
description: Field description displayed on the signing form. Supports Markdown.
validation:
type: object
description: Field validation rules.
properties:
pattern:
type: string
description: HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
example: '[A-Z]{4}'
message:
type: string
description: A custom error message to display on validation failure.
min:
oneOf:
- type: number
- type: string
description: Minimum allowed number value or date depending on field type.
max:
oneOf:
- type: number
- type: string
description: Maximum allowed number value or date depending on field type.
step:
type: number
description: Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
preferences:
type: object
description: Field display preferences.
properties:
font_size:
type: integer
description: Font size of the field value in pixels.
example: 12
font_type:
type: string
description: Font type of the field value.
enum:
- bold
- italic
- bold_italic
font:
type: string
description: Font family of the field value.
enum:
- Times
- Helvetica
- Courier
color:
type: string
description: Font color of the field value.
enum:
- black
- white
- blue
default: black
background:
type: string
description: Field box background color.
enum:
- black
- white
- blue
align:
type: string
description: Horizontal alignment of the field text value.
enum:
- left
- center
- right
default: left
valign:
type: string
description: Vertical alignment of the field text value.
enum:
- top
- center
- bottom
default: center
format:
type: string
description: 'The data format for different field types.<br>- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).<br>- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.<br>- Number field: accepts currency formats such as usd, eur, gbp.'
example: DD/MM/YYYY
price:
type: number
description: Price value of the payment field. Only for payment fields.
example: 99.99
currency:
type: string
description: Currency value of the payment field. Only for payment fields.
enum:
- USD
- EUR
- GBP
- CAD
- AUD
default: USD
mask:
description: Set `true` to make sensitive data masked on the document.
oneOf:
- type: integer
- type: boolean
default: false
reasons:
description: An array of signature reasons to choose from.
type: array
items:
type: string
roles:
type: array
description: A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docuseal/refs/heads/main/openapi/docuseal-submissions-api-openapi.yml