Explore Our API

You can also discover our API with Postman and OpenAPI.

Submissions

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}

List all submissions

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);
});
Example Response
{
  "data": [
    {
      "id": 1,
      "source": "link",
      "submitters_order": "random",
      "slug": "VyL4szTwYoSvXq",
      "audit_log_url": "https://docuseal.co/blobs/proxy/hash/example.pdf",
      "created_at": "2023-12-10T15:48:17.166Z",
      "updated_at": "2023-12-10T15:49:21.895Z",
      "archived_at": null,
      "submitters": [
        {
          "id": 1,
          "unid": "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",
          "created_at": "2023-12-10T15:48:17.173Z",
          "updated_at": "2023-12-14T15:50:21.799Z",
          "name": "John Doe",
          "phone": "+1234567890",
          "status": "completed"
        }
      ],
      "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 a submission

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);
});
Example Response
{
  "id": 1,
  "source": "link",
  "submitters_order": "random",
  "slug": "VyL4szTwYoSvXq",
  "audit_log_url": "https://docuseal.co/blobs/proxy/hash/example.pdf",
  "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,
      "unid": "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",
      "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",
      "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",
  "completed_at": "2023-12-14T15:49:21.701Z"
}

Create a submission

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 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.

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

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);
});
Example Response
[
  {
  "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,
  "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"
}
]

Create submissions from emails

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);
});
Example Response
[
  {
  "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,
  "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,
  "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"
}
]

Archive a submission

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);
});
Example Response
{
  "id": 1,
  "archived_at": "2023-12-14T15:50:21.799Z"
}

Submitters

Submitters API allows you to load all details provided by the signer of the document.

get

/submitters

get

/submitters/{id}

put

/submitters/{id}

List all submitters

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);
});
Example Response
{
  "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",
      "created_at": "2023-12-14T15:48:17.173Z",
      "updated_at": "2023-12-14T15:50:21.799Z",
      "name": "John Doe",
      "phone": "+1234567890",
      "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 a submitter

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);
});
Example Response
{
  "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",
  "created_at": "2023-12-14T15:48:17.173Z",
  "updated_at": "2023-12-14T15:50:21.799Z",
  "name": "John Doe",
  "phone": "+1234567890",
  "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"
}

Update a submitter

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);
});
Example Response
{
  "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",
  "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

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}

List all templates

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);
});
Example Response
{
  "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,
      "account_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 a template

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);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Create a template from Word DOCX

Pro

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 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 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);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Create a template from HTML

Pro

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);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Merge templates

Pro

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 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);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Create a template from existing PDF

Pro

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: 0}]}]
      }
    ]
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Clone a template

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);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Update a template

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);
});
Example Response
{
  "id": 1,
  "updated_at": "2023-12-14T15:50:21.799Z"
}

Update template documents

Pro

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.

Example: base64

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.

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

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: 'base64'}]}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
Example Response
{
  "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,
  "account_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"
    }
  ]
}

Archive a template

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);
});