API Reference | DocuSeal Docs

Docs
API Reference

Send signature request

Learn More →

Upload PDF to sign

Download signed PDFs

HTML to signing form

Explore Our API

You can also discover our API with Postman and OpenAPI.

Get API key Run in Postman OpenAPI Specs

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.

Copy

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

Copy

{
  "data": [
    {
      "id": 1,
      "source": "link",
      "submitters_order": "random",
      "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.

Copy

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

Copy

{
  "id": 1,
  "source": "link",
  "submitters_order": "random",
  "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,
      "submission_id": 1,
      "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

Copy

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

Copy

[
  {
  "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}}.

Copy

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

Copy

[
  {
  "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.

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Default:

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

Copy

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

Copy

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

get

/templates

get

/templates/{id}

post

/templates/docx

post

/templates/html

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.

Copy

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

Copy

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

Copy

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

Copy

{
  "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

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

Copy

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

Copy

{
  "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

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.

name String

Template name. Random uuid will be assigned when not specified.

Example: Test Template

Copy

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

Copy

{
  "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"
    }
  ]
}

Create a template from existing 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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

{
  "id": 1,
  "updated_at": "2023-12-14T15:50:21.799Z"
}

Update template documents

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

Copy

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

Copy

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

Copy

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

Example Response

Copy

{
  "id": 1,
  "archived_at": "2023-12-14T15:50:21.799Z"
}

Webhooks

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 URL

Form Webhook

During the form filling process, various types of events may occur and are dispatched at different stages:

'form.viewed' event is triggered when the submitter first opens the form.
'form.started' event is triggered when the submitter initiates filling out the form.
'form.completed' event is triggered upon successful form completion and signing.

It's important to note that each of these events contain information available at the time of dispatch, so some data may be missing or incomplete depending on the specific event. Failed webhook requests (4xx, 5xx) are automatically retried multiple times within 48 hours (every 2^attempt minutes) for all production accounts.
Related Guides
Download Signed Documents

event_type String

The event type.

Possible values: form.viewed, form.started, form.completed

timestamp String

The event timestamp.

Example: 2023-09-24T11:20:42Z

data Object

Submitted data object.

id Number

The submitter's unique identifier.

submission_id Number

The unique submission identifier.

email String

The submitter's email address

Example: john.doe@example.com

ua String

The user agent string that provides information about the submitter's web browser.

Example: 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 String

The submitter's IP address.

name String

The submitter's name.

phone String

The submitter's phone number, formatted according to the E.164 standard.

Example: +1234567890

role String

The submitter's role name or title.

Example: First Party

external_id String

Your application-specific unique string key to identify submitter within your app.

application_key String

Your application-specific unique string key to identify submitter within your app. Backward compatibility with the previous version of the API. Use external_id instead.

sent_at String

status String

The submission status.

opened_at String

completed_at String

created_at String

updated_at String

submission Object

The submission details.

id Number

The submission's unique identifier.

audit_log_url String

The audit log PDF URL. Available only if the submission was completted by all submitters.

status String

The submission status.

url String

The submission URL.

created_at String

The submission creation date.

template Object

Base template details.

id Number

The template's unique identifier.

name String

The template's name.

external_id String

Your application-specific unique string key to identify template within your app.

created_at String

updated_at String

preferences Object

send_email Boolean

The flag indicating whether the submitter has opted to receive an email.

send_sms Boolean

The flag indicating whether the submitter has opted to receive an SMS.

values Array

List of the filled values passed by the submitter.

Child parameters

field String

The field name.

values String

The field value.

metadata Object

Submitter metadata object with custom data fields.

audit_log_url String

The audit log PDF URL. Available only if the submission was completted by all submitters.

submission_url String

The submission URL.

documents Array

Child parameters

name String

The document file name.

url String

The document file URL.

Copy

{
  "event_type": "form.completed",
  "timestamp": "2023-09-24T13:48:36Z",
  "data": {
    "id": 1,
    "submission_id": 12,
    "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",
    "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,
    "application_key": null,
    "status": "completed",
    "preferences": {
      "send_email": true,
      "send_sms": false
    },
    "submission": {
      "id": 12,
      "audit_log_url": "https://docuseal.co/blobs/proxy/eyJfcmFpbHMiOnsib/audit-log.pdf",
      "status": "completed",
      "url": "https://docuseal.co/e/N5JsdkFGPeQF7J",
      "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"
    },
    "values": [
      {
        "field": "First Name",
        "value": "John"
      },
      {
        "field": "Last Name",
        "value": "Doe"
      },
      {
        "field": "Signature",
        "value": "https://docuseal.co/blobs/proxy/eyJfcmFpbHMiOnsib/signature.png"
      },
      {
        "field": "Signature",
        "value": "John Doe"
      }
    ],
    "metadata": {
      "customData": "custom value"
    },
    "audit_log_url": "https://docuseal.co/blobs/proxy/eyJfcmFpbHMiOnsib/audit-log.pdf",
    "submission_url": "https://docuseal.co/e/N5JsdkFGPeQF7J",
    "documents": [
      {
        "name": "sample-document",
        "url": "https://docuseal.co/blobs/proxy/eyJfcmFpbHMiOnsib/sample-document.pdf"
      }
    ]
  }
}