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

The API endpoint provides the ability to retrieve a list of available submissions.

Parameters

template_id optional Integer

The unique identifier of the document template. Allows to receive only submissions for a specific template.

application_key optional String

Filter submissions by the given `application_key` value.

template_folder optional String

Filter submissions by template folder name.

limit optional Integer

The number of submissions to return. Default value is 10. Maximum value is 100.

before optional Integer

The unique identifier of the submission to end the list with. Allows to receive only submissions with id less than the specified value.

after optional Integer

The unique identifier of the submission to start the list from. Allows to receive only submissions with id greater than the specified value.

get

/submissions 

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

Get a submission

The API endpoint provides the functionality to retrieve information about a submission.

Parameters

id required Integer

The unique identifier of the submission.

get

/submissions/{id} 

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

Create a submission

This API endpoint allows you to create submissions for a document template and send them to the specified submitters

Request Body Properties

template_id required Integer

The unique identifier of the template.

send_email optional Boolean

Set `false` to disable signature request emails sending.

Default: true

send_sms optional Boolean

Set `true` to send signature request via phone number and SMS.

Default: false

order optional 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

message optional Object

subject optional String

Custom signature request email subject.

body optional String

Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.

submission required Array

The list of the submission.

Child parameters

submitters required Array

The list of submitters for the submission.

Child parameters

name optional String

The name of the submitter.

role optional String

The role name or title of the submitter.

Example: First Submitter

email required String

The email address of the submitter.

Example: john.doe@example.com

phone optional String

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

Example: +1234567890

values optional Object

An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param.

application_key optional String

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

send_email optional Boolean

Set `false` to disable signature request emails sending.

Default: true

send_sms optional Boolean

Set `true` to send signature request via phone number and SMS.

Default: false

fields optional Array

A list of configurations for template document form fields.

Child parameters

name required String

Document template field name

Example: First Name

default_value optional String

Default value of the field. Use public URL to the image file to set default signature or image fields.

Example: Acme

validation_pattern optional 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 optional String

A custom message to display on pattern validation failure.

readonly optional Boolean

Set `true` to make it impossible for the submitter to edit predefined field value.

Default: false

post

/submissions 

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,
    send_sms: false,
    order: 'preserved',
    message: {subject: 'string', body: 'string'},
    submission: [
      {
        submitters: [
          {
            name: 'string',
            role: 'First Submitter',
            email: 'john.doe@example.com',
            phone: '+1234567890',
            values: {},
            application_key: 'string',
            send_email: true,
            send_sms: false,
            fields: [
              {
                name: 'First Name',
                default_value: 'Acme',
                validation_pattern: '[A-Z]{4}',
                invalid_message: 'string',
                readonly: false
              }
            ]
          }
        ]
      }
    ]
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Create submissions from emails

This API endpoint allows you to create submissions for a document template and send them to the specified email addresses.

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 optional Boolean

Set `false` to disable signature request emails sending.

Default: true

message optional Object

subject optional String

Custom signature request email subject.

body optional String

Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}.

post

/submissions/emails 

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',
    send_email: true,
    message: {subject: 'string', body: 'string'}
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Archive a submission

The API endpoint allows to archive a submission.

Parameters

id required Integer

The unique identifier of the submission.

delete

/submissions/{id} 

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

Submitters

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

get

/submitters

get

/submitters/{id}

List all submitters

The API endpoint provides the ability to retrieve a list of submitters.

Parameters

submission_id optional Integer

The unique identifier of the submission. Allows to receive only submitters for a submission.

application_key optional String

The unique applications-specific identifier provided for a submitter when initializing a signature request. Allows to receive only submitters with a specified application key.

limit optional Integer

The number of submitters to return. Default value is 10. Maximum value is 100.

before optional Integer

The unique identifier of the submitter to end the list with. Allows to receive only submitters with id less than the specified value.

after optional Integer

The unique identifier of the submitter to start the list from. Allows to receive only submitters with id greater than the specified value.

get

/submitters 

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

Get a submitter

The API endpoint provides the functionality to retrieve information about a submitter.

Parameters

id required Integer

The unique identifier of the submitter.

get

/submitters/{id} 

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

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/html

post

/templates/pdf

post

/templates/{id}/clone

put

/templates/{id}

delete

/templates/{id}

List all templates

The API endpoint provides the ability to retrieve a list of available document templates.

Parameters

application_key optional String

The unique applications-specific identifier provided for the template via API or Embedded template form builder. Allows to receive only templates with your specified application key.

folder optional String

Filter templates by folder name.

archived optional Boolean

Get only archived templates instead of active ones.

limit optional Integer

The number of templates to return. Default value is 10. Maximum value is 100.

before optional Integer

The unique identifier of the template to end the list with. Allows to receive only templates with id less than the specified value.

after optional Integer

The unique identifier of the template to start the list from. Allows to receive only templates with id greater than the specified value.

get

/templates 

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

Get a template

The API endpoint provides the functionality to retrieve information about a document template.

Parameters

id required Integer

The unique identifier of the document template.

get

/templates/{id} 

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

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

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" submitter="First Submitter" required="false" style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px"> </text-field> and typesetting industry</p>

name optional String

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

Example: Test Template

size optional 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

application_key optional String

Your application-specific unique string key to identify this template within your app. Existing template with specified `application_key` will be updated with a new HTML.

Example: 714d974e-83d8-11ee-b962-0242ac120002

post

/templates/html 

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  submitter="First Submitter"\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',
    size: 'A4',
    application_key: '714d974e-83d8-11ee-b962-0242ac120002'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Create a template from existing PDF

The API endpoint provides the functionality to create a fillable document template for existing PDF. It requires to specify the exact pixel coordinates of the document fields. Alternatively, use HTML API to generate PDF documents with fields already defined in it.

Request Body Properties

application_key String

Your unique application key

Example: unique-key

name String

Name of the PDF template

Example: Test PDF

documents Array

Child parameters

name String

Name of the document

file String

Base64-encoded content of the PDF file

fields Array

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

post

/templates/pdf 

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: {
    application_key: 'unique-key',
    name: 'Test PDF',
    documents: [
      {
        name: 'string',
        file: 'string',
        fields: [
          {
            name: 'string',
            role: 'string',
            type: 'text',
            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);
});

Clone a template

The API endpoint allows to clone existing template into a new template.

Parameters

id required Integer

The unique identifier of the document template.

Request Body Properties

name optional String

Template name. Existing name with (Clone) suffix will be used if not specified.

Example: Clone Template

folder_name required String

The folder's name to which the template should be cloned.

application_key optional String

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

post

/templates/{id}/clone 

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: 'Clone Template', folder_name: 'string', application_key: 'string'}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Move a template to a different folder

The API endpoint provides the functionality to move a document template to a different folder.

Parameters

id required Integer

The unique identifier of the document template.

Request Body Properties

template Object

folder_name required String

The folder's name to which the template should be moved

put

/templates/{id} 

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: {template: {folder_name: 'string'}}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Archive a template

The API endpoint allows to archive a document template.

Parameters

id required Integer

The unique identifier of the document template.

delete

/templates/{id} 

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

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.

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 Submitter

application_key String

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

sent_at String

opened_at String

completed_at String

created_at String

updated_at String

template Object

Base template details.

id Number

The template's unique identifier.

name String

The template's name.

created_at String

updated_at String

values Array

List of the filled values passed by the submitter.

Child parameters

field String

The field name.

values String

The field value.

audit_log_url String

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

documents Array

Child parameters

name String

The document file name.

url String

The document file URL.

{
  "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 Submitter",
    "application_key": null,
    "template": {
      "id": 6,
      "name": "Invoice",
      "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": "http://example.com/blobs/proxy/eyJfcmFpbHMiOnsib/signature.png"
      },
      {
        "field": "Signature",
        "value": "John Doe"
      }
    ],
    "audit_log_url": "http://example.com/blobs/proxy/eyJfcmFpbHMiOnsib/audit-log.pdf",
    "documents": [
      {
        "name": "sample-document",
        "url": "http://example.com/blobs/proxy/eyJfcmFpbHMiOnsib/sample-document.pdf"
      }
    ]
  }
}