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.
The API endpoint provides the ability to retrieve a list of available submissions.
Parameters
The template ID allows you to receive only the submissions created from that specific template.
Filter submissions by status.
Possible values completed, declined, expired, pending
Filter submissions based on submitter's name, email or phone partial match.
Filter submissions by unique slug.
Example NtLDQM7eJX2ZMd
Filter submissions by template folder name.
Returns only archived submissions when
true
and only active submissions when
false
.
The number of submissions to return. Default value is 10. Maximum value is 100.
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.
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.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const { data, pagination } = await resp.json();{
"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
}
}The API endpoint provides the functionality to retrieve information about a submission.
Parameters
The unique identifier of the submission.
Example 1001
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/1001", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const submission = await resp.json();{
"id": 1,
"name": null,
"source": "link",
"submitters_order": "random",
"slug": "VyL4szTwYoSvXq",
"audit_log_url": "https://docuseal.com/blobs/proxy/hash/example.pdf",
"combined_document_url": null,
"completed_at": "2023-12-14T15:49:21.701Z",
"expire_at": null,
"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-14T15:48:17.173Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "John Doe",
"phone": "+1234567890",
"external_id": null,
"status": "completed",
"metadata": {},
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "example",
"url": "https://docuseal.com/blobs/proxy/hash/example.pdf"
}
],
"role": "First Party"
}
],
"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"
},
"submission_events": [
{
"id": 1,
"submitter_id": 2,
"event_type": "view_form",
"event_timestamp": "2023-12-14T15:47:24.566Z",
"data": {}
}
],
"documents": [
{
"name": "example",
"url": "https://docuseal.com/file/hash/example.pdf"
}
],
"status": "completed"
}This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned.
Parameters
The unique identifier of the submission.
Example 1001
When
true
, merges all documents into a single PDF.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/1001/documents", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const submission = await resp.json();{
"id": 1,
"documents": [
{
"name": "example",
"url": "https://docuseal.com/file/hash/example.pdf"
}
]
}This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers).
Related Guides
Send documents for signature via API
Pre-fill PDF document form fields with API
Request Body Properties
The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.
Example 1000001
Set
false
to disable signature request emails sending.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
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
Possible values random, preserved
Specify URL to redirect to after the submission completion.
Specify BCC address to send signed documents to after the completion.
Specify Reply-To address to use in the notification emails.
Specify the expiration date and time after which the submission becomes unavailable for signature.
Example 2024-09-01 12:00:00 UTC
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"}
Custom signature request email message.
Custom signature request email subject.
Custom signature request email body. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
The list of submitters for the submission.
The name of the submitter.
The role name or title of the submitter.
Example First Party
The email address of the submitter.
Example john.doe@example.com
The phone number of the submitter, formatted according to the E.164 standard.
Example +1234567890
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see
fields
param.
Your application-specific unique string key to identify this submitter within your app.
Pass
true
to mark submitter as completed and auto-signed via API.
Metadata object with additional submitter information.
Example { "customField": "value" }
Set
false
to disable signature request emails sending only for this submitter.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
Specify Reply-To address to use in the notification emails for this submitter.
Submitter specific URL to redirect to after the submission completion.
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.
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
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
Custom signature request email message for the submitter.
Custom signature request email subject for the submitter.
Custom signature request email body for the submitter. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
A list of configurations for template document form fields.
Document template field name.
Example First Name
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
Set
true
to make it impossible for the submitter to edit predefined field value.
Default false
Set
true
to make the field required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
template_id: 1000001,
send_email: true,
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
});
const submitters = await resp.json();[
{
"id": 1,
"submission_id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "john.doe@example.com",
"slug": "pAMimKcyrLjqVt",
"sent_at": "2023-12-13T23:04:04.252Z",
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "string",
"phone": "+1234567890",
"external_id": "2321",
"metadata": {
"customData": "custom value"
},
"status": "sent",
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"preferences": {
"send_email": true,
"send_sms": false
},
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}
]The API endpoint provides the functionality to create one-off submission request from a PDF. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form
Request Body Properties
Name of the document submission.
Example Test Submission Document
Set
false
to disable signature request emails sending.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
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
Possible values random, preserved
Specify URL to redirect to after the submission completion.
Specify BCC address to send signed documents to after the completion.
Specify Reply-To address to use in the notification emails.
Specify the expiration date and time after which the submission becomes unavailable for signature.
Example 2024-09-01 12:00:00 UTC
An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.
An array of PDF documents to create a submission.
Name of the document.
Base64-encoded content of the PDF file or downloadable file URL.
Example base64
Fields are optional if you use {{...}} text tags to define fields in the document.
Name of the field.
Type of the field (e.g., text, signature, date, initials).
Possible values heading, text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone, verification, kba, strikethrough
Role name of the signer.
Indicates if the field is required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
List of areas where the field is located in the document.
X-coordinate of the field area.
Y-coordinate of the field area.
Width of the field area.
Height of the field area.
Page number of the field area. Starts from 1.
Example 1
Option string value for
radio
and
multiple
select field types.
An array of option values for
select
field type.
Example ["Option A","Option B"]
Document position in the submission. If not specified, the document will be added in the order it appears in the documents array.
The list of submitters for the submission.
The name of the submitter.
The role name or title of the submitter.
Example First Party
The email address of the submitter.
Example john.doe@example.com
The phone number of the submitter, formatted according to the E.164 standard.
Example +1234567890
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see
fields
param.
Your application-specific unique string key to identify this submitter within your app.
Pass
true
to mark submitter as completed and auto-signed via API.
Metadata object with additional submitter information.
Example { "customField": "value" }
Set
false
to disable signature request emails sending only for this submitter.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
Specify Reply-To address to use in the notification emails for this submitter.
Submitter specific URL to redirect to after the submission completion.
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.
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
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
Set the role name of the previous party that should invite this party via email.
Custom signature request email message for the submitter.
Custom signature request email subject for the submitter.
Custom signature request email body for the submitter. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
A list of configurations for template document form fields.
Document template field name.
Example First Name
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
Set
true
to make it impossible for the submitter to edit predefined field value.
Default false
Set
true
to make the field required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
Custom signature request email message.
Custom signature request email subject.
Custom signature request email body. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
Remove PDF form fields from the documents.
Default false
Set
true
to merge the documents into a single PDF file.
Default false
Pass
false
to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.
Default true
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/pdf", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test Submission Document",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
});
const submission = await resp.json();{
"id": 5,
"name": "Test Submission",
"submitters": [
{
"id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "john.doe@example.com",
"slug": "pAMimKcyrLjqVt",
"sent_at": "2025-06-02T15:55:51.310Z",
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2025-06-02T15:55:50.320Z",
"updated_at": "2025-06-02T15:55:50.320Z",
"name": "string",
"phone": "+1234567890",
"external_id": "2321",
"metadata": {
"customData": "custom value"
},
"status": "sent",
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"preferences": {
"send_email": true,
"send_sms": false,
"reply_to": "reply@example.com",
"completed_redirect_url": "https://example.com/"
},
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}
],
"source": "api",
"submitters_order": "preserved",
"status": "pending",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"expire_at": null,
"created_at": "2025-06-02T15:55:50.270Z"
}The API endpoint provides functionality to create a one-off submission request from a DOCX file with dynamic content variables. Use [[variable_name]] text tags to define dynamic content variables in the document. See https://www.docuseal.com/examples/demo_template.docx for the specific text variable syntax, including dynamic content tables and lists. You can also use the {{signature}} field syntax to define fillable fields, as in a PDF.
Related Guides
Use dynamic content variables in DOCX to create personalized documents
Request Body Properties
Name of the document submission.
Example Test Submission Document
Set
false
to disable signature request emails sending.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.
Example {"variable_name":"value"}
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
Possible values random, preserved
Specify URL to redirect to after the submission completion.
Specify BCC address to send signed documents to after the completion.
Specify Reply-To address to use in the notification emails.
Specify the expiration date and time after which the submission becomes unavailable for signature.
Example 2024-09-01 12:00:00 UTC
An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.
An array of DOCX documents to create a submission.
Name of the document.
Base64-encoded content of the PDF or DOCX file or downloadable file URL.
Example base64
Document position in the submission. If not specified, the document will be added in the order it appears in the documents array.
The list of submitters for the submission.
The name of the submitter.
The role name or title of the submitter.
Example First Party
The email address of the submitter.
Example john.doe@example.com
The phone number of the submitter, formatted according to the E.164 standard.
Example +1234567890
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see
fields
param.
Your application-specific unique string key to identify this submitter within your app.
Pass
true
to mark submitter as completed and auto-signed via API.
Metadata object with additional submitter information.
Example { "customField": "value" }
Set
false
to disable signature request emails sending only for this submitter.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
Specify Reply-To address to use in the notification emails for this submitter.
Submitter specific URL to redirect to after the submission completion.
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.
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
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
Set the role name of the previous party that should invite this party via email.
Custom signature request email message for the submitter.
Custom signature request email subject for the submitter.
Custom signature request email body for the submitter. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
A list of configurations for template document form fields.
Document template field name.
Example First Name
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
Set
true
to make it impossible for the submitter to edit predefined field value.
Default false
Set
true
to make the field required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
Custom signature request email message.
Custom signature request email subject.
Custom signature request email body. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
Set
true
to merge the documents into a single PDF file.
Default false
Pass
false
to disable the removal of {{text}} tags from the document. This can be used along with transparent text tags for faster and more robust document processing.
Default true
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/docx", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test Submission Document",
variables: {
variable_name: "value"
},
documents: [
{
name: "string",
file: "base64"
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
});
const submitters = await resp.json();{
"id": 5,
"name": "Test Submission",
"submitters": [
{
"id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "john.doe@example.com",
"slug": "pAMimKcyrLjqVt",
"sent_at": "2025-06-02T15:55:51.310Z",
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2025-06-02T15:55:50.320Z",
"updated_at": "2025-06-02T15:55:50.320Z",
"name": "string",
"phone": "+1234567890",
"external_id": "2321",
"metadata": {
"customData": "custom value"
},
"status": "sent",
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"preferences": {
"send_email": true,
"send_sms": false,
"reply_to": "reply@example.com",
"completed_redirect_url": "https://example.com/"
},
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}
],
"source": "api",
"submitters_order": "preserved",
"status": "pending",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"expire_at": null,
"created_at": "2025-06-02T15:55:50.270Z"
}This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML
Request Body Properties
Name of the document submission.
Example Test Submission Document
Set
false
to disable signature request emails sending.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
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
Possible values random, preserved
Specify URL to redirect to after the submission completion.
Specify BCC address to send signed documents to after the completion.
Specify Reply-To address to use in the notification emails.
Specify the expiration date and time after which the submission becomes unavailable for signature.
Example 2024-09-01 12:00:00 UTC
An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.
The list of documents built from HTML. Can be used to create a submission with multiple documents.
Document name. Random uuid will be assigned when not specified.
Example Test Document
HTML document content with field tags.
Example <p>Lorem Ipsum is simply dummy text of the <text-field name="Industry" role="First Party" required="false" style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px"> </text-field> and typesetting industry</p>
HTML document content of the header to be displayed on every page.
HTML document content of the footer to be displayed on every page.
Page size. Letter 8.5 x 11 will be assigned when not specified.
Default Letter
Possible values Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6
Example A4
Document position in the submission. If not specified, the document will be added in the order it appears in the documents array.
The list of submitters for the submission.
The name of the submitter.
The role name or title of the submitter.
Example First Party
The email address of the submitter.
Example john.doe@example.com
The phone number of the submitter, formatted according to the E.164 standard.
Example +1234567890
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see
fields
param.
Your application-specific unique string key to identify this submitter within your app.
Pass
true
to mark submitter as completed and auto-signed via API.
Metadata object with additional submitter information.
Example { "customField": "value" }
Set
false
to disable signature request emails sending only for this submitter.
Default true
Set
true
to send signature request via phone number and SMS.
Default false
Specify Reply-To address to use in the notification emails for this submitter.
Submitter specific URL to redirect to after the submission completion.
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.
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
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
Set the role name of the previous party that should invite this party via email.
Custom signature request email message for the submitter.
Custom signature request email subject for the submitter.
Custom signature request email body for the submitter. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
A list of configurations for template document form fields.
Document template field name.
Example First Name
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
Set
true
to make it impossible for the submitter to edit predefined field value.
Default false
Set
true
to make the field required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
Custom signature request email message.
Custom signature request email subject.
Custom signature request email body. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}.
Set
true
to merge the documents into a single PDF file.
Default false
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/html", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test Submission Document",
documents: [
{
name: "Test Document",
html: `<p>Lorem Ipsum is simply dummy text of the
<text-field
name="Industry"
role="First Party"
required="false"
style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">
</text-field>
and typesetting industry</p>
`
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
});
const submission = await resp.json();{
"id": 5,
"name": "Test Submission",
"submitters": [
{
"id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "john.doe@example.com",
"slug": "pAMimKcyrLjqVt",
"sent_at": "2025-06-02T15:55:51.310Z",
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2025-06-02T15:55:50.320Z",
"updated_at": "2025-06-02T15:55:50.320Z",
"name": "string",
"phone": "+1234567890",
"external_id": "2321",
"metadata": {
"customData": "custom value"
},
"status": "sent",
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"preferences": {
"send_email": true,
"send_sms": false,
"reply_to": "reply@example.com",
"completed_redirect_url": "https://example.com/"
},
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}
],
"source": "api",
"submitters_order": "preserved",
"status": "pending",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"expire_at": null,
"created_at": "2025-06-02T15:55:50.270Z"
}The API endpoint allows you to update a submission: change its name, expiration date, and archive or unarchive it.
Parameters
The unique identifier of the submission.
Example 1001
Request Body Properties
The name of the submission.
Example New Submission Name
The date and time when the submission will expire and no longer be available. Pass
null
to remove the expiration.
Example 2024-09-01 12:00:00 UTC
Set
true
to archive the submission or
false
to unarchive it.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/1001", {
method: "PUT",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "New Submission Name",
expire_at: "2024-09-01 12:00:00 UTC",
archived: true
})
});
const submission = await resp.json();{
"id": 1,
"name": null,
"source": "link",
"submitters_order": "random",
"slug": "VyL4szTwYoSvXq",
"audit_log_url": "https://docuseal.com/blobs/proxy/hash/example.pdf",
"combined_document_url": null,
"completed_at": "2023-12-14T15:49:21.701Z",
"expire_at": null,
"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-14T15:48:17.173Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "John Doe",
"phone": "+1234567890",
"external_id": null,
"status": "completed",
"metadata": {},
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "example",
"url": "https://docuseal.com/blobs/proxy/hash/example.pdf"
}
],
"role": "First Party"
}
],
"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"
},
"documents": [
{
"name": "example",
"url": "https://docuseal.com/file/hash/example.pdf"
}
],
"status": "completed"
}The API endpoint allows you to archive a submission.
Parameters
The unique identifier of the submission.
Example 1001
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/1001", {
method: "DELETE",
headers: {
"X-Auth-Token": "API_KEY"
}
});
await resp.json();{
"id": 1,
"archived_at": "2023-12-14T15:50:21.799Z"
}Submitters API allows you to load all details provided by the signer of the document.
The API endpoint provides the ability to retrieve a list of submitters.
Parameters
The submission ID allows you to receive only the submitters related to that specific submission.
Filter submitters on name, email or phone partial match.
Filter submitters by unique slug.
Example zAyL9fH36Havvm
The date and time string value to filter submitters that completed the submission after the specified date and time.
Example 2024-03-05 9:32:20
The date and time string value to filter submitters that completed the submission before the specified date and time.
Example 2024-03-06 19:32:20
The unique application-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external ID.
The number of submitters to return. Default value is 10. Maximum value is 100.
The unique identifier of the submitter to start the list from. It allows you to receive only submitters with an ID greater than the specified value. Pass ID value from the
pagination.next
response to load the next batch of submitters.
The unique identifier of the submitter to end the list with. It allows you to receive only submitters with an ID less than the specified value.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submitters", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const { data, pagination } = await resp.json();{
"data": [
{
"id": 7,
"submission_id": 3,
"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-14T15:48:17.173Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "John Doe",
"phone": "+1234567890",
"status": "completed",
"external_id": null,
"preferences": {},
"metadata": {},
"template": {
"id": 2,
"name": "Example Template",
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z"
},
"submission_events": [
{
"id": 12,
"submitter_id": 7,
"event_type": "view_form",
"event_timestamp": "2023-12-14T15:48:17.351Z",
"data": {}
}
],
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "sample-document",
"url": "https://docuseal.com/file/eyJfcmFpbHMiOnsiIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--f9758362acced0f3c86cdffad02800e/sample-document.pdf"
}
],
"role": "First Party"
}
],
"pagination": {
"count": 1,
"next": 1,
"prev": 1
}
}The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values.
Parameters
The unique identifier of the submitter.
Example 500001
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submitters/500001", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const submitter = await resp.json();{
"id": 7,
"submission_id": 3,
"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-10T15:49:21.701Z",
"declined_at": null,
"created_at": "2023-12-14T15:48:17.173Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "John Doe",
"phone": "+1234567890",
"status": "completed",
"external_id": null,
"metadata": {},
"preferences": {},
"template": {
"id": 2,
"name": "Example Template",
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z"
},
"submission_events": [
{
"id": 12,
"submitter_id": 7,
"event_type": "view_form",
"event_timestamp": "2023-12-14T15:47:17.351Z",
"data": {}
}
],
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "sample-document",
"url": "https://docuseal.com/file/hash/sample-document.pdf"
}
],
"role": "First Party"
}The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API
Parameters
The unique identifier of the submitter.
Example 500001
Request Body Properties
The name of the submitter.
The email address of the submitter.
Example john.doe@example.com
The phone number of the submitter, formatted according to the E.164 standard.
Example +1234567890
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see
fields
param.
Your application-specific unique string key to identify this submitter within your app.
Set
true
to re-send signature request emails.
Set
true
to re-send signature request via phone number SMS.
Default false
Specify Reply-To address to use in the notification emails.
Pass
true
to mark submitter as completed and auto-signed via API.
Metadata object with additional submitter information.
Example { "customField": "value" }
Submitter specific URL to redirect to after the submission completion.
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
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
Custom signature request email message.
Custom signature request email subject.
Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.
A list of configurations for template document form fields.
Document template field name.
Example First Name
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
Set
true
to make it impossible for the submitter to edit predefined field value.
Default false
Set
true
to make the field required.
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submitters/500001", {
method: "PUT",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
email: "john.doe@example.com",
fields: [
{
name: "First Name",
default_value: "Acme"
}
]
})
});
const submitter = await resp.json();{
"id": 1,
"submission_id": 12,
"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-10T15:49:21.701Z",
"declined_at": null,
"created_at": "2023-12-14T15:48:17.173Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"name": "John Doe",
"phone": "+1234567890",
"status": "completed",
"external_id": null,
"metadata": {},
"preferences": {},
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [],
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}Templates represent reusable document signing forms with fields and signatures to be collected. It's possible to create unique template forms with fields and signatures using HTML or with tagged PDFs.
The API endpoint provides the ability to retrieve a list of available document templates.
Parameters
Filter templates based on the name partial match.
Filter templates by unique slug.
Example opaKWh8WWTAcVG
The unique application-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external ID.
Filter templates by folder name.
List only archived templates instead of active ones.
List templates shared with test mode.
The number of templates to return. Default value is 10. Maximum value is 100.
The unique identifier of the template to start the list from. It allows you to receive only templates with an ID greater than the specified value. Pass ID value from the
pagination.next
response to load the next batch of templates.
The unique identifier of the template to end the list with. It allows you to receive only templates with an ID less than the specified value.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const { data, pagination } = await resp.json();{
"data": [
{
"id": 1,
"slug": "iRgjDX7WDK6BRo",
"name": "Example Template",
"preferences": {},
"schema": [
{
"attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"name": "example-document"
}
],
"fields": [
{
"uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02",
"submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0",
"name": "Full Name",
"type": "text",
"required": true,
"preferences": {},
"areas": [
{
"x": 0.2638888888888889,
"y": 0.168958742632613,
"w": 0.325,
"h": 0.04616895874263263,
"attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"page": 0
}
]
}
],
"submitters": [
{
"name": "First Party",
"uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:21:57.375Z",
"updated_at": "2023-12-14T15:22:55.094Z",
"source": "native",
"folder_id": 1,
"folder_name": "Default",
"external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5",
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 5,
"uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"url": "https://docuseal.com/file/hash/sample-document.pdf",
"preview_image_url": "https://docuseal.com/file/hash/0.jpg",
"filename": "example-document.pdf"
}
]
}
],
"pagination": {
"count": 1,
"next": 1,
"prev": 2
}
}The API endpoint provides the functionality to retrieve information about a document template.
Parameters
The unique identifier of the document template.
Example 1000001
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/1000001", {
method: "GET",
headers: {
"X-Auth-Token": "API_KEY"
}
});
const template = await resp.json();{
"id": 1,
"slug": "iRgjDX7WDK6BRo",
"name": "Example Template",
"preferences": {},
"schema": [
{
"attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"name": "example-document"
}
],
"fields": [
{
"uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02",
"submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0",
"name": "Full Name",
"type": "text",
"required": true,
"preferences": {},
"areas": [
{
"x": 0.2638888888888889,
"y": 0.168958742632613,
"w": 0.325,
"h": 0.04616895874263263,
"attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"page": 0
}
]
}
],
"submitters": [
{
"name": "First Party",
"uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:21:57.375Z",
"updated_at": "2023-12-14T15:22:55.094Z",
"source": "native",
"folder_id": 1,
"folder_name": "Default",
"external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5",
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 5,
"uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
"url": "https://docuseal.com/file/hash/sample-document.pdf",
"preview_image_url": "https://docuseal.com/file/hash/0.jpg",
"filename": "example-document.pdf"
}
]
}The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form
Request Body Properties
Name of the template.
Example Test PDF
The folder's name in which the template should be created.
Your application-specific unique string key to identify this template within your app. Existing template with specified
external_id
will be updated with a new PDF.
Example unique-key
Set to
true
to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.
Default true
An array of PDF documents to create a template.
Name of the document.
Base64-encoded content of the PDF file or downloadable file URL.
Example base64
Fields are optional if you use {{...}} text tags to define fields in the document.
Name of the field.
Type of the field (e.g., text, signature, date, initials).
Possible values heading, text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone, verification, kba, strikethrough
Role name of the signer.
Indicates if the field is required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
List of areas where the field is located in the document.
X-coordinate of the field area.
Y-coordinate of the field area.
Width of the field area.
Height of the field area.
Page number of the field area. Starts from 1.
Example 1
Option string value for
radio
and
multiple
select field types.
An array of option values for
select
field type.
Example ["Option A","Option B"]
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
Remove PDF form fields from the documents.
Default false
Pass
false
to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.
Default true
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/pdf", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test PDF",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
]
})
});
const template = await resp.json();{
"id": 5,
"slug": "s3ff992CoPjvaX",
"name": "Demo PDF",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "Submitter",
"uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 1,
"folder_name": "Default",
"external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5",
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 7,
"uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"url": "https://docuseal.com/file/hash/Demo%20PDF.pdf"
}
]
}The API endpoint provides the functionality to create a fillable document template for an existing Microsoft Word document. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.docx for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form
Request Body Properties
Name of the template.
Example Test DOCX
Your application-specific unique string key to identify this template within your app. Existing template with specified
external_id
will be updated with a new document.
Example unique-key
The folder's name in which the template should be created.
Set to
true
to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.
Default true
An array of DOCX documents to create a template.
Name of the document.
Base64-encoded content of the DOCX file or downloadable file URL.
Example base64
Set to
true
to make the document dynamic. When enabled, the DOCX document content can be edited or use [[variables]] in the template editor.
Default false
Fields are optional if you use {{...}} text tags to define fields in the document.
Name of the field.
Type of the field (e.g., text, signature, date, initials).
Possible values heading, text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone, verification, kba, strikethrough
Role name of the signer.
Indicates if the field is required.
Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
Field description displayed on the signing form. Supports Markdown.
List of areas where the field is located in the document.
X-coordinate of the field area.
Y-coordinate of the field area.
Width of the field area.
Height of the field area.
Page number of the field area. Starts from 1.
Example 1
Option string value for
radio
and
multiple
select field types.
An array of option values for
select
field type.
Example ["Option A","Option B"]
Field validation rules.
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example [A-Z]{4}
A custom error message to display on validation failure.
Minimum allowed number value or date depending on field type.
Maximum allowed number value or date depending on field type.
Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
Field display preferences.
Font size of the field value in pixels.
Example 12
Font type of the field value.
Possible values bold, italic, bold_italic
Font family of the field value.
Possible values Times, Helvetica, Courier
Font color of the field value.
Default black
Example black
Field box background color.
Example black
Horizontal alignment of the field text value.
Default left
Possible values left, center, right
Vertical alignment of the field text value.
Default center
Possible values top, center, bottom
The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.
Example DD/MM/YYYY
Price value of the payment field. Only for payment fields.
Example 99.99
Currency value of the payment field. Only for payment fields.
Default USD
Possible values USD, EUR, GBP, CAD, AUD, CHF, SEK
Set
true
to make sensitive data masked on the document.
Default false
An array of signature reasons to choose from.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/docx", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test DOCX",
documents: [
{
name: "string",
file: "base64"
}
]
})
});
const template = await resp.json();{
"id": 5,
"slug": "s3ff992CoPjvaX",
"name": "Demo PDF",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "Submitter",
"uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 1,
"folder_name": "Default",
"external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5",
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 7,
"uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"url": "https://docuseal.com/hash/DemoPDF.pdf"
}
]
}The API endpoint provides the functionality to seamlessly generate a PDF document template by utilizing the provided HTML content while incorporating pre-defined fields.
Related Guides
Create PDF document fillable form with HTML
Request Body Properties
HTML template with field tags.
Example <p>Lorem Ipsum is simply dummy text of the <text-field name="Industry" role="First Party" required="false" style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px"> </text-field> and typesetting industry</p>
HTML template of the header to be displayed on every page.
HTML template of the footer to be displayed on every page.
Template name. Random uuid will be assigned when not specified.
Example Test Template
Page size. Letter 8.5 x 11 will be assigned when not specified.
Default Letter
Possible values Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6
Example A4
Your application-specific unique string key to identify this template within your app. Existing template with specified
external_id
will be updated with a new HTML.
Example 714d974e-83d8-11ee-b962-0242ac120002
The folder's name in which the template should be created.
Set to
true
to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.
Default true
The list of documents built from HTML. Can be used to create a template with multiple documents. Leave
documents
param empty when using a top-level
html
param for a template with a single document.
HTML template with field tags.
Example <p>Lorem Ipsum is simply dummy text of the <text-field name="Industry" role="First Party" required="false" style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px"> </text-field> and typesetting industry</p>
Document name. Random uuid will be assigned when not specified.
Example Test Document
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/html", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
html: `<p>Lorem Ipsum is simply dummy text of the
<text-field
name="Industry"
role="First Party"
required="false"
style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">
</text-field>
and typesetting industry</p>
`,
name: "Test Template"
})
});
const template = await resp.json();{
"id": 3,
"slug": "ZQpF222rFBv71q",
"name": "Demo Template",
"schema": [
{
"name": "Demo Template",
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5"
}
],
"fields": [
{
"name": "Name",
"required": false,
"type": "text",
"uuid": "a06c49f6-4b20-4442-ac7f-c1040d2cf1ac",
"submitter_uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3",
"areas": [
{
"page": 0,
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "Submitter",
"uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 1,
"folder_name": "Default",
"external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c",
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 3,
"uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"url": "https://docuseal.com/file/hash/Test%20Template.pdf"
}
]
}The API endpoint allows you to clone an existing template into a new template.
Parameters
The unique identifier of the document template.
Example 1000001
Request Body Properties
Template name. Existing name with (Clone) suffix will be used if not specified.
Example Cloned Template
The folder's name to which the template should be cloned.
Your application-specific unique string key to identify this template within your app.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/1000001/clone", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Cloned Template"
})
});
const template = await resp.json();{
"id": 6,
"slug": "Xc7opTqwwV9P7x",
"name": "Cloned Template",
"schema": [
{
"attachment_uuid": "68aa0716-61f0-4535-9ba4-6c00f835b080",
"name": "sample-document"
}
],
"fields": [
{
"uuid": "93c7065b-1b19-4551-b67b-9946bf1c11c9",
"submitter_uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5",
"name": "Name",
"type": "text",
"required": true,
"areas": [
{
"page": 0,
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "First Party",
"uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 2,
"folder_name": "Default",
"external_id": null,
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 9,
"uuid": "ded62277-9705-4fac-b5dc-58325d4102eb",
"url": "https://docuseal.com/file/hash/sample-document.pdf",
"filename": "sample-document.pdf"
}
]
}The API endpoint allows you to merge multiple templates with documents and fields into a new combined template.
Request Body Properties
An array of template ids to merge into a new template.
Example [321,432]
Template name. Existing name with (Merged) suffix will be used if not specified.
Example Merged Template
The name of the folder in which the merged template should be placed.
Your application-specific unique string key to identify this template within your app.
Set to
true
to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.
Default true
An array of submitter role names to be used in the merged template.
Example ["Agent","Customer"]
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/merge", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
template_ids: [
321,
432
],
name: "Merged Template"
})
});
const template = await resp.json();{
"id": 6,
"slug": "Xc7opTqwwV9P7x",
"name": "Merged Template",
"schema": [
{
"attachment_uuid": "68aa0716-61f0-4535-9ba4-6c00f835b080",
"name": "sample-document"
}
],
"fields": [
{
"uuid": "93c7065b-1b19-4551-b67b-9946bf1c11c9",
"submitter_uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5",
"name": "Name",
"type": "text",
"required": true,
"areas": [
{
"page": 0,
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "First Party",
"uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 2,
"folder_name": "Default",
"external_id": null,
"shared_link": true,
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 9,
"uuid": "ded62277-9705-4fac-b5dc-58325d4102eb",
"url": "https://docuseal.com/file/hash/sample-document.pdf",
"filename": "sample-document.pdf"
}
]
}The API endpoint provides the functionality to move a document template to a different folder and update the name of the template.
Parameters
The unique identifier of the document template.
Example 1000001
Request Body Properties
The name of the template.
Example New Document Name
The folder's name to which the template should be moved.
Example New Folder
An array of submitter role names to update the template with.
Example ["Agent","Customer"]
Set
false
to unarchive template.
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/1000001", {
method: "PUT",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "New Document Name",
folder_name: "New Folder"
})
});
const template = await resp.json();{
"id": 1,
"updated_at": "2023-12-14T15:50:21.799Z"
}The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content.
Parameters
The unique identifier of the document template.
Example 1000001
Request Body Properties
The list of documents to add or replace in the template.
Document name. Random uuid will be assigned when not specified.
Example Test Template
Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param.
HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL.
Position of the document. By default will be added as the last document in the template.
Example 0
Set to
true
to replace existing document with a new file at
position
. Existing document fields will be transferred to the new document if it doesn't contain any fields.
Default false
Set to
true
to remove existing document at given
position
or with given
name
.
Default false
Set to
true
to merge all existing and new documents into a single PDF document in the template.
Default false
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/1000001/documents", {
method: "PUT",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
documents: [
{
file: "string"
}
]
})
});
const template = await resp.json();{
"id": 3,
"slug": "ZQpF222rFBv71q",
"name": "Demo Template",
"schema": [
{
"name": "Demo Template",
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5"
}
],
"fields": [
{
"name": "Name",
"required": false,
"type": "text",
"uuid": "a06c49f6-4b20-4442-ac7f-c1040d2cf1ac",
"submitter_uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3",
"areas": [
{
"page": 0,
"attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"submitters": [
{
"name": "Submitter",
"uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2023-12-14T15:50:21.799Z",
"updated_at": "2023-12-14T15:50:21.799Z",
"source": "api",
"folder_id": 1,
"folder_name": "Default",
"external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c",
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 3,
"uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5",
"url": "https://docuseal.com/file/hash/Test%20Template.pdf"
}
]
}The API endpoint allows you to archive a document template.
Parameters
The unique identifier of the document template.
Example 1000001
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/templates/1000001", {
method: "DELETE",
headers: {
"X-Auth-Token": "API_KEY"
}
});
await resp.json();{
"id": 1,
"archived_at": "2023-12-14T15:50:21.799Z"
}Send document signing events to a preconfigured webhook URL. You can use this feature to capture and process document-related events in real-time.
Set webhook URLPayload
The event type.
Possible values form.viewed, form.started, form.completed, form.declined
The event timestamp.
Example 2023-09-24T11:20:42Z
Submitted form data object.
The submitter's unique identifier.
The unique submission identifier.
The submitter's email address.
Example john.doe@example.com
The submitter's phone number, formatted according to the E.164 standard.
Example +1234567890
The submitter's name.
The user agent string that provides information about the submitter's web browser.
The submitter's IP address.
The date and time when the signing request was sent to the submitter.
The date and time when the submitter opened the signing form.
The date and time when the submitter completed the signing form.
The date and time when the submitter declined the signing form.
The reason provided by the submitter for declining the signing form.
The date and time when the submitter was created.
The date and time when the submitter was last updated.
Your application-specific unique string key to identify the submitter.
Possible values completed, declined, opened, sent, awaiting
The role name of the submitter.
Metadata object with additional submitter information.
Submitter preferences.
An array of the filled values submitted by the submitter.
Document template field name.
Pre-filled value of the field.
An array of the completed documents.
Document name.
Document URL.
Audit log file URL.
The submission URL.
Unique identifier of the document template.
The name of the template.
Your application-specific unique string key to identify this template within your app.
Folder name where the template is located.
The date and time when the template was created.
The date and time when the template was last updated.
Submission details of the form.
The submission unique identifier.
Audit log file URL.
Combined PDF file URL with documents and Audit Log.
Possible values completed, declined, expired, pending
The submission URL.
Dynamic document content variables of the submission.
The date and time when the submission was created.
{
"event_type": "form.completed",
"timestamp": "2023-09-24T13:48:36Z",
"data": {
"id": 1,
"email": "john.doe@example.com",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
"ip": "132.216.88.83",
"sent_at": "2023-08-20T10:09:05.459Z",
"opened_at": "2023-08-20T10:10:00.451Z",
"completed_at": "2023-08-20T10:12:47.579Z",
"declined_at": null,
"created_at": "2023-08-20T10:09:02.459Z",
"updated_at": "2023-08-20T10:12:47.907Z",
"name": null,
"phone": null,
"role": "First Party",
"external_id": null,
"decline_reason": null,
"status": "completed",
"preferences": {
"send_email": true,
"send_sms": false
},
"submission": {
"id": 12,
"audit_log_url": "https://docuseal.com/blobs/proxy/eyJfcmFpbHMiOnsib/audit-log.pdf",
"combined_document_url": "https://docuseal.com/blobs/proxy/eyJfcmFpbHMiOnsib/document.pdf",
"status": "completed",
"url": "https://docuseal.com/e/N5JsdkFGPeQF7J",
"variables": {
"custom_variable": "value"
},
"created_at": "2023-08-20T10:09:05.258Z"
},
"template": {
"id": 6,
"name": "Invoice",
"external_id": null,
"created_at": "2023-08-19T11:09:21.487Z",
"updated_at": "2023-08-19T11:11:47.804Z",
"folder_name": "Default"
},
"values": [
{
"field": "First Name",
"value": "John"
},
{
"field": "Last Name",
"value": "Doe"
},
{
"field": "Signature",
"value": "https://docuseal.com/blobs/proxy/eyJfcmFpbHMiOnsib/signature.png"
},
{
"field": "Signature",
"value": "John Doe"
}
],
"metadata": {
"customData": "custom value"
},
"audit_log_url": "https://docuseal.com/blobs/proxy/eyJfcmFpbHMiOnsib/audit-log.pdf",
"submission_url": "https://docuseal.com/e/N5JsdkFGPeQF7J",
"documents": [
{
"name": "sample-document",
"url": "https://docuseal.com/blobs/proxy/eyJfcmFpbHMiOnsib/sample-document.pdf"
}
]
}
}Payload
The event type.
Possible values submission.created, submission.completed, submission.expired, submission.archived
The event timestamp.
Example 2023-09-24T11:20:42Z
Submission unique ID number.
Name of the document submission.
Example Test Submission Document
Unique slug of the submission.
The source of the submission.
Possible values invite, bulk, api, embed, link
The order of submitters.
Possible values random, preserved
Audit log file URL.
Combined PDF file URL with documents and Audit Log.
The date and time when the submission was created.
The date and time when the submission was last updated.
The date and time when the submission was archived.
The date and time when the submission will expire and no longer be available for signing.
Dynamic content variables object used in dynamic template documents.
The list of submitters.
Submitter unique ID number.
Submission unique ID number.
Submitter UUID.
The email address of the submitter.
Unique key to be used in the form signing link and embedded form.
The date and time when the signing request was sent to the submitter.
The date and time when the submitter opened the signing form.
The date and time when the submitter completed the signing form.
The date and time when the submitter declined the signing form.
The date and time when the submitter was created.
The date and time when the submitter was last updated.
The name of the submitter.
The phone number of the submitter.
Your application-specific unique string key to identify this submitter within your app.
The status of signing request for the submitter.
Possible values completed, declined, opened, sent, awaiting
An array of pre-filled values for the submitter.
Document template field name.
Pre-filled value of the field.
An array of completed or signed documents by the submitter.
Document name.
Document URL.
The role of the submitter in the signing process.
Metadata object with additional submitter information.
Submitter preferences.
Unique identifier of the document template.
The name of the template.
Your application-specific unique string key to identify this template within your app.
Folder name where the template is located.
The date and time when the template was created.
The date and time when the template was last updated.
An array of events related to the submission.
Submission event unique ID number.
Unique identifier of the submitter that triggered the event.
Event type.
Possible values send_email, bounce_email, complaint_email, send_reminder_email, send_sms, send_2fa_sms, open_email, click_email, click_sms, phone_verified, start_form, start_verification, complete_verification, view_form, invite_party, complete_form, decline_form, api_complete_form
Date and time when the event was triggered.
Additional event details object.
An array of completed or signed documents of the submission.
Document name.
Document URL.
The status of the submission.
Possible values completed, declined, expired, pending
The date and time when the submission was completed.
{
"event_type": "submission.created",
"timestamp": "2024-05-26T17:32:33.518Z",
"data": {
"id": 1,
"name": "Sample Submission",
"slug": "VyL4szTwYoSvXq",
"expire_at": null,
"archived_at": null,
"created_at": "2024-05-26T17:32:33.447Z",
"updated_at": "2024-05-26T17:32:33.447Z",
"source": "invite",
"submitters_order": "random",
"audit_log_url": null,
"combined_document_url": null,
"submitters": [
{
"id": 1,
"submission_id": 1,
"uuid": "6b92a2d0-b511-4678-bccf-1e8a131f5030",
"email": "mike@example.com",
"slug": "S6fWFYRZus6suW",
"sent_at": null,
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2024-05-26T17:32:33.466Z",
"updated_at": "2024-05-26T17:32:33.466Z",
"name": null,
"phone": null,
"external_id": null,
"metadata": {},
"status": "awaiting",
"values": [],
"documents": [],
"preferences": {},
"role": "First Party"
}
],
"template": {
"id": 1,
"name": "Sample Document",
"created_at": "2024-05-26T16:57:28.092Z",
"updated_at": "2024-05-26T16:58:07.314Z",
"external_id": null,
"folder_name": "Default"
},
"variables": {
"custom_variable": "value"
},
"created_by_user": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"submission_events": [],
"documents": [],
"status": "pending",
"completed_at": null
}
}Payload
The event type.
Possible values template.created, template.updated, template.archived
The event timestamp.
Example 2023-09-24T11:20:42Z
Unique identifier of the document template.
Unique slug of the document template.
The name of the template.
Template preferences.
List of documents attached to the template.
Unique identifier of the attached document.
Name of the attached document.
List of fields to be filled in the template.
Unique identifier of the field.
Unique identifier of the submitter that filled the field.
Field name.
Type of the field (e.g., text, signature, date, initials).
Possible values heading, text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone, verification, kba, strikethrough
Field display preferences.
Font size of the field value in pixels.
Font type of the field value.
Font family of the field value.
Font color of the field value.
Field box background color.
Horizontal alignment of the field text value.
Vertical alignment of the field text value.
The data format for different field types.
Price value of the payment field. Only for payment fields.
Currency value of the payment field. Only for payment fields.
Indicates if the field is masked on the document.
An array of signature reasons to choose from.
List of areas where the field is located in the document.
X coordinate of the area where the field is located in the document.
Y coordinate of the area where the field is located in the document.
Width of the area where the field is located in the document.
Height of the area where the field is located in the document.
Unique identifier of the attached document where the field is located.
Page number of the attached document where the field is located.
Schema of the dynamic document content variables used in the template.
The list of submitters for the template.
The name of the submitter.
Unique identifier of the submitter.
Unique identifier of the author of the template.
Date and time when the template was archived.
The date and time when the template was created.
The date and time when the template was last updated.
Source of the template.
Possible values native, api, embed
Your application-specific unique string key to identify this template within your app.
Unique identifier of the folder where the template is located.
Folder name where the template is located.
Indicates if the template is accessible by link.
Unique identifier of the user.
The first name of the user.
The last name of the user.
The email address of the user.
List of documents attached to the template.
Unique identifier of the document.
Unique identifier of the document.
URL of the document.
Document preview image URL.
Document filename.
{
"event_type": "template.created",
"timestamp": "2024-05-26T16:59:47.237Z",
"data": {
"id": 1,
"slug": "UwRU9ir5dvhSRY",
"name": "Sample Document",
"schema": [
{
"attachment_uuid": "84fa7c01-8b89-47e2-83f0-8623e7e4aa1c",
"name": "sample-document"
}
],
"fields": [
{
"uuid": "f86dbf07-2d84-490c-b372-1aaaaf0549c1",
"submitter_uuid": "6b92a2d0-b511-4678-bccf-1e8a131f5030",
"name": "First Name",
"type": "text",
"required": true,
"preferences": {},
"areas": [
{
"x": 0.2541666666666667,
"y": 0.2266854052667579,
"w": 0.3132975260416667,
"h": 0.04878270348837208,
"attachment_uuid": "84fa7c01-8b89-47e2-83f0-8623e7e4aa1c",
"page": 0
}
]
},
{
"uuid": "1b41711b-f765-41c5-b2b9-000b88b96c6e",
"submitter_uuid": "6b92a2d0-b511-4678-bccf-1e8a131f5030",
"name": "Last Name",
"type": "text",
"required": true,
"preferences": {},
"areas": [
{
"x": 0.5419813368055556,
"y": 0.3057829599863201,
"w": 0.2188802083333333,
"h": 0.05516843365253077,
"attachment_uuid": "84fa7c01-8b89-47e2-83f0-8623e7e4aa1c",
"page": 0
}
]
}
],
"submitters": [
{
"name": "First Party",
"uuid": "6b92a2d0-b511-4678-bccf-1e8a131f5030"
}
],
"author_id": 1,
"archived_at": null,
"created_at": "2024-05-26T16:57:28.092Z",
"updated_at": "2024-05-26T16:57:28.092Z",
"source": "native",
"folder_id": 1,
"external_id": null,
"preferences": {},
"shared_link": false,
"folder_name": "Default",
"author": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"documents": [
{
"id": 12,
"uuid": "84fa7c01-8b89-47e2-83f0-8623e7e4aa1c",
"url": "https://docuseal.com/file/hash/sample-document.pdf",
"preview_image_url": "https://docuseal.com/file/hash/0.jpg",
"filename": "sample-document.pdf"
}
]
}
}