Send signature request
Upload PDF to sign
Download signed PDFs
HTML to signing form
Explore Our API
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.
get
/submissions
get
/submissions/{id}
post
/submissions
post
/submissions/emails
delete
/submissions/{id}
get
/submissions
The API endpoint provides the ability to retrieve a list of available submissions.
Parameters
template_id Integer
The template ID allows you to receive only the submissions created from that specific template.
q String
Filter submissions based on submitters name, email or phone partial match.
template_folder String
Filter submissions by template folder name.
limit Integer
The number of submissions to return. Default value is 10. Maximum value is 100.
after Integer
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.
before Integer
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.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/submissions',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"data": [
{
"id": 1,
"source": "link",
"submitters_order": "random",
"slug": "VyL4szTwYoSvXq",
"status": "completed",
"audit_log_url": "https://docuseal.co/blobs/proxy/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
}
}get
/submissions/{id}
The API endpoint provides the functionality to retrieve information about a submission.
Parameters
id required Integer
The unique identifier of the submission.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/submissions/1001',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"id": 1,
"source": "link",
"submitters_order": "random",
"slug": "VyL4szTwYoSvXq",
"audit_log_url": "https://docuseal.co/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.co/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"
}
],
"documents": [
{
"name": "example",
"url": "https://docuseal.co/blobs/proxy/hash/example.pdf"
}
],
"status": "completed"
}post
/submissions
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
template_id required Integer
The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.
send_email Boolean
Set `false` to disable signature request emails sending.
Default: true
send_sms Boolean
Set `true` to send signature request via phone number and SMS.
Default: false
order String
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: preserved, random
completed_redirect_url String
Specify URL to redirect to after the submission completion.
bcc_completed String
Specify BCC address to send signed documents to after the completion.
reply_to String
Specify Reply-To address to use in the notification emails.
expire_at String
Specify the expiration date and time after which the submission becomes unavailable for signature.
Example: 2024-09-01 12:00:00 UTC
message Object
subject String
Custom signature request email subject.
body String
Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.
submitters required Array
The list of submitters for the submission.
Child parameters
name String
The name of the submitter.
role String
The role name or title of the submitter.
Example: First Party
email required String
The email address of the submitter.
Example: john.doe@example.com
phone String
The phone number of the submitter, formatted according to the E.164 standard.
Example: +1234567890
values Object
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 String
Your application-specific unique string key to identify this submitter within your app.
completed Boolean
Pass `true` to mark submitter as completed and auto-signed via API.
metadata Object
An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param.
Example: { "customField": "value" }
send_email Boolean
Set `false` to disable signature request emails sending.
Default: true
send_sms Boolean
Set `true` to send signature request via phone number and SMS.
Default: false
completed_redirect_url String
Submitter specific URL to redirect to after the submission completion.
fields Array
A list of configurations for template document form fields.
Child parameters
name required String
Document template field name
Example: First Name
description String
Description of the field to be displayed on the signing form. Can accept markdown.
default_value String
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
validation_pattern String
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example: [A-Z]{4}
invalid_message String
A custom message to display on pattern validation failure.
readonly Boolean
Set `true` to make it impossible for the submitter to edit predefined field value.
Default: false
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/submissions',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {
template_id: 1000001,
send_email: true,
submitters: [{role: 'First Party', email: 'john.doe@example.com'}]
}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});[
{
"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.co/s/pAMimKcyrLjqVt"
}
]post
/submissions/emails
This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools.
Request Body Properties
template_id required Integer
The unique identifier of the template.
emails required String
A comma-separated list of email addresses to send the submission to.
Example: hi@docuseal.co, example@docuseal.co
send_email Boolean
Set `false` to disable signature request emails sending.
Default: true
message Object
subject String
Custom signature request email subject.
body String
Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/submissions/emails',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {template_id: 1000001, emails: 'hi@docuseal.co, example@docuseal.co'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});[
{
"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.co/s/pAMimKcyrLjqVt"
},
{
"id": 2,
"submission_id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "alan.smith@example.com",
"slug": "SEwc65vHNDH3QS",
"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": "Roe Moe"
}
],
"preferences": {
"send_email": true,
"send_sms": false
},
"role": "First Party",
"embed_src": "SEwc65vHNDH3QS"
}
]delete
/submissions/{id}
The API endpoint allows you to archive a submission.
Parameters
id required Integer
The unique identifier of the submission.
var axios = require("axios").default;
var options = {
method: 'DELETE',
url: 'https://api.docuseal.co/submissions/1001',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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.
get
/submitters
get
/submitters/{id}
put
/submitters/{id}
get
/submitters
The API endpoint provides the ability to retrieve a list of submitters.
Parameters
submission_id Integer
The submission ID allows you to receive only the submitters related to that specific submission.
q String
Filter submitters on name, email or phone partial match.
completed_after String
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
completed_before String
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
external_id String
The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id.
limit Integer
The number of submitters to return. Default value is 10. Maximum value is 100.
after Integer
The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters.
before Integer
The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/submitters',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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"
}
],
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "sample-document",
"url": "https://docuseal.co/blobs_proxy/eyJfcmFpbHMiOnsiIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--f9758362acced0f3c86cdffad02800e/sample-document.pdf"
}
],
"role": "First Party"
}
],
"pagination": {
"count": 1,
"next": 1,
"prev": 1
}
}get
/submitters/{id}
The API endpoint provides the functionality to retrieve information about a submitter.
Parameters
id required Integer
The unique identifier of the submitter.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/submitters/500001',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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"
}
],
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
{
"name": "sample-document",
"url": "https://docuseal.co/blobs/proxy/hash/sample-document.pdf"
}
],
"role": "First Party"
}put
/submitters/{id}
The API endpoint provides allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API
Parameters
id required Integer
The unique identifier of the submitter.
Request Body Properties
name String
The name of the submitter.
email String
The email address of the submitter.
Example: john.doe@example.com
phone String
The phone number of the submitter, formatted according to the E.164 standard.
Example: +1234567890
values Object
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 String
Your application-specific unique string key to identify this submitter within your app.
send_email Boolean
Set `true` to re-send signature request emails.
send_sms Boolean
Set `true` to re-send signature request via phone number SMS.
Default: false
reply_to String
Specify Reply-To address to use in the notification emails.
completed_redirect_url String
Submitter specific URL to redirect to after the submission completion.
completed Boolean
Pass `true` to mark submitter as completed and auto-signed via API.
message Object
subject String
Custom signature request email subject.
body String
Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.
fields Array
A list of configurations for template document form fields.
Child parameters
name required String
Document template field name
Example: First Name
default_value String
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
validation_pattern String
HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
Example: [A-Z]{4}
invalid_message String
A custom message to display on pattern validation failure.
readonly Boolean
Set `true` to make it impossible for the submitter to edit predefined field value.
Default: false
var axios = require("axios").default;
var options = {
method: 'PUT',
url: 'https://api.docuseal.co/submitters/500001',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {
email: 'john.doe@example.com',
fields: [{name: 'First Name', default_value: 'Acme'}]
}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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",
"values": [
{
"field": "Full Name",
"value": "John Doe"
}
],
"documents": [
],
"role": "First Party"
}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.
get
/templates
get
/templates/{id}
post
/templates/docx
post
/templates/html
post
/templates/merge
post
/templates/pdf
post
/templates/{id}/clone
put
/templates/{id}
put
/templates/{id}/documents
delete
/templates/{id}
get
/templates
The API endpoint provides the ability to retrieve a list of available document templates.
Parameters
q String
Filter templates based on the name partial match.
external_id String
The unique applications-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.
folder String
Filter templates by folder name.
archived Boolean
Get only archived templates instead of active ones.
limit Integer
The number of templates to return. Default value is 10. Maximum value is 100.
after Integer
The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates.
before Integer
The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/templates',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"data": [
{
"id": 1,
"slug": "iRgjDX7WDK6BRo",
"name": "Example Template",
"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,
"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",
"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.co/disk/hash/sample-document.pdf",
"preview_image_url": "https://docuseal.co/disk/hash/0.jpg",
"filename": "example-document.pdf"
}
]
}
],
"pagination": {
"count": 1,
"next": 1,
"prev": 2
}
}get
/templates/{id}
The API endpoint provides the functionality to retrieve information about a document template.
Parameters
id required Integer
The unique identifier of the document template.
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://api.docuseal.co/templates/1000001',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"id": 1,
"slug": "iRgjDX7WDK6BRo",
"name": "Example Template",
"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,
"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",
"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.co/disk/hash/sample-document.pdf",
"preview_image_url": "https://docuseal.co/disk/hash/0.jpg",
"filename": "example-document.pdf"
}
]
}post
/templates/docx
The API endpoint provides the functionality to create a fillable document template for existing Microsoft Word document. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.co/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 String
Name of the template
Example: Test DOCX
external_id String
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
folder_name String
The folder's name to which the template should be created.
documents required Array
Child parameters
name required String
Name of the document
file required String
Base64-encoded content of the DOCX file or downloadable file URL
Example: base64
fields Array
Fields are optional if you use {{...}} text tags to define fields in the document.
Child parameters
name String
Name of the field
role String
Role name of the signer
type String
Type of the field (e.g., text, signature, date, initials)
Possible values: text, signature, initials, date, image, file, payment, stamp, select, checkbox, multiple, radio, cells, phone
areas Array
Child parameters
x Number
X-coordinate of the field area
y Number
Y-coordinate of the field area
w Number
Width of the field area
h Number
Height of the field area
page Integer
Page number of the field area. Starts from 1.
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/templates/docx',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {name: 'Test DOCX', documents: [{name: 'string', file: 'base64'}]}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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",
"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.co/hash/DemoPDF.pdf"
}
]
}post
/templates/html
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 required String
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_header String
HTML template of the header to be displayed on every page.
html_footer String
HTML template of the footer to be displayed on every page.
name String
Template name. Random uuid will be assigned when not specified.
Example: Test Template
size String
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
external_id String
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
folder_name String
The folder's name to which the template should be created.
documents Array
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.
Child parameters
html required String
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>
name String
Template name. Random uuid will be assigned when not specified.
Example: Test Template
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/templates/html',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {
html: '<p>Lorem Ipsum is simply dummy text of the\n<text-field\n name="Industry"\n role="First Party"\n required="false"\n style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">\n</text-field>\nand typesetting industry</p>\n',
name: 'Test Template'
}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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.co/hash/Test%20Template.pdf"
}
]
}post
/templates/merge
The API endpoint allows you to merge multiple templates with documents and fields into a new combined template.
Request Body Properties
template_ids required Array
An array of template ids to merge into a new template.
Example: [321,432]
name String
Template name. Existing name with (Merged) suffix will be used if not specified.
Example: Merged Template
folder_name String
The name of the folder in which the merged template should be placed.
external_id String
Your application-specific unique string key to identify this template within your app.
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/templates/merge',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {template_ids: [321, 432], name: 'Merged Template'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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,
"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.co/hash/sample-document.pdf",
"filename": "sample-document.pdf"
}
]
}post
/templates/pdf
The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.co/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 String
Name of the template
Example: Test PDF
folder_name String
The folder's name to which the template should be created.
external_id String
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
documents required Array
Child parameters
name required String
Name of the document
file required String
Base64-encoded content of the PDF file or downloadable file URL
Example: base64
fields Array
Fields are optional if you use {{...}} text tags to define fields in the document.
Child parameters
name String
Name of the field
role String
Role name of the signer
type String
Type of the field (e.g., text, signature, date, initials)
Possible values: text, signature, initials, date, image, file, payment, stamp, select, checkbox, multiple, radio, cells, phone
areas Array
Child parameters
x required Number
X-coordinate of the field area
y required Number
Y-coordinate of the field area
w required Number
Width of the field area
h required Number
Height of the field area
page required Integer
Page number of the field area. Starts from 1.
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/templates/pdf',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {
name: 'Test PDF',
documents: [
{
name: 'string',
file: 'base64',
fields: [{name: 'string', areas: [{x: 0, y: 0, w: 0, h: 0, page: 1}]}]
}
]
}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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",
"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.co/hash/Demo%20PDF.pdf"
}
]
}post
/templates/{id}/clone
The API endpoint allows you to clone existing template into a new template.
Parameters
id required Integer
The unique identifier of the documents template.
Request Body Properties
name String
Template name. Existing name with (Clone) suffix will be used if not specified.
Example: Cloned Template
folder_name String
The folder's name to which the template should be cloned.
external_id String
Your application-specific unique string key to identify this template within your app.
var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://api.docuseal.co/templates/1000001/clone',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {name: 'Cloned Template'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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,
"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.co/hash/sample-document.pdf",
"filename": "sample-document.pdf"
}
]
}put
/templates/{id}
The API endpoint provides the functionality to move a document template to a different folder and update the name of the template.
Parameters
id required Integer
The unique identifier of the document template.
Request Body Properties
name String
The name of the template
Example: New Document Name
folder_name String
The folder's name to which the template should be moved
Example: New Folder
roles Array
An array of submitter role names to update the template with.
Example: ["Agent","Customer"]
archived Boolean
Set `false` to unarchive template.
var axios = require("axios").default;
var options = {
method: 'PUT',
url: 'https://api.docuseal.co/templates/1000001',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {name: 'New Document Name', folder_name: 'New Folder'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"id": 1,
"updated_at": "2023-12-14T15:50:21.799Z"
}put
/templates/{id}/documents
The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content.
Parameters
id required Integer
The unique identifier of the documents template.
Request Body Properties
documents Array
The list of documents to add or replace in the template.
Child parameters
name String
Document name. Random uuid will be assigned when not specified.
Example: Test Template
file String
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 String
HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL.
position Integer
Position of the document. By default will be added as the last document in the template.
Example: 0
replace Boolean
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
remove Boolean
Set to `true` to remove existing document at given `position` or with given `name`.
Default: false
merge Boolean
Set to `true` to merge all existing and new documents into a single PDF document in the template.
Default: false
var axios = require("axios").default;
var options = {
method: 'PUT',
url: 'https://api.docuseal.co/templates/1000001/documents',
headers: {'X-Auth-Token': 'API_KEY', 'content-type': 'application/json'},
data: {documents: [{file: 'string'}]}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});{
"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.co/hash/Test%20Template.pdf"
}
]
}delete
/templates/{id}
The API endpoint allows you to archive a document template.
Parameters
id required Integer
The unique identifier of the document template.
var axios = require("axios").default;
var options = {
method: 'DELETE',
url: 'https://api.docuseal.co/templates/1000001',
headers: {'X-Auth-Token': 'API_KEY'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});