# API Reference

Servers:
- `https://api.docuseal.com` (Global Server)
- `https://api.docuseal.eu` (EU Server)
- On-premises installations use their own host

Authentication: send your API key in the `X-Auth-Token` header.

## Guides

- [Send signature request](https://www.docuseal.com/docs/api/create-a-submission.md)
- [Upload PDFs to sign](https://www.docuseal.com/docs/api/create-a-submission-from-pdf.md)
- [HTML to signing form](https://www.docuseal.com/docs/api/create-a-submission-from-html.md)
- [Download signed PDFs](https://www.docuseal.com/guides/download-signed-documents.md)
- [Learn from Guides](https://www.docuseal.com/guides.md)

## Explore our API

You can discover our API with Postman and OpenAPI or code with AI.

- [API Key](https://docuseal.com/sign_up?redir=https%3A%2F%2Fconsole.docuseal.com%2Fapi)
- [Postman](https://www.postman.com/docuseal/docuseal/collection/baauu23/docuseal-api)
- [OpenAPI](https://editor.swagger.io/?url=https%3A%2F%2Fconsole.docuseal.com%2Fopenapi.yml)

## AI plugins

### Add to Claude Code

1. Add the plugin repository:

```bash
claude plugin marketplace add docusealco/docuseal-agent-skills
```

2. Install the plugin in your project:

```bash
claude plugin install docuseal@docuseal-agent-skills
```

### Add to Codex

1. Add the plugin repository:

```bash
codex plugin marketplace add docusealco/docuseal-agent-skills
```

2. Install the plugin in your project:

```bash
codex plugin add docuseal@docuseal-agent-skills
```

### Add to Hermes Agent

Install the CLI skill:

```bash
hermes skills install docusealco/docuseal-agent-skills/skills/docuseal-cli
```

Hermes prompts for `DOCUSEAL_API_KEY` on first use and passes it through to the terminal sandbox.

### Add Code Skills

Universal skills work in any code agent (Cursor, GitHub Copilot, Gemini CLI and many others).

1. Run the install command:

```bash
npx skills add docusealco/docuseal-agent-skills --skill docuseal-code
```

2. Select "Global" or "Project" installation and proceed through the wizard.


### MCP

MCP server: `https://mcp.docuseal.com`

- [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=DocuSeal&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.docuseal.com%22%7D)
- [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=DocuSeal&config=eyJ1cmwiOiJodHRwczovL21jcC5kb2N1c2VhbC5jb20ifQ==)
- Add to Claude Code:

```bash
claude mcp add --transport http docuseal https://mcp.docuseal.com/
```

### Languages

| Language | Install | GitHub |
| --- | --- | --- |
| JavaScript | `npm install @docuseal/api` | https://github.com/docusealco/docuseal-js |
| TypeScript | `npm install @docuseal/api` | https://github.com/docusealco/docuseal-js |
| Python | `pip install docuseal` | https://github.com/docusealco/docuseal-python |
| Ruby | `gem install docuseal` | https://github.com/docusealco/docuseal-ruby |
| PHP | `composer require docusealco/docuseal-php` | https://github.com/docusealco/docuseal-php |
| Java | `implementation 'com.docuseal:docuseal-java:+'` | https://github.com/docusealco/docuseal-java |
| C# | `dotnet add package Docuseal` | https://github.com/docusealco/docuseal-dotnet |
| Go | `go get github.com/docusealco/docuseal-go` | https://github.com/docusealco/docuseal-go |
| cURL | `curl https://api.docuseal.com/templates -H 'X-Auth-Token: API_KEY'` |  |
| CLI | `npm install -g docuseal` | https://github.com/docusealco/docuseal-cli |

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

### List all submissions

- [GET /submissions](https://www.docuseal.com/docs/api/list-all-submissions.md)

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

### Get a submission

- [GET /submissions/{id}](https://www.docuseal.com/docs/api/get-a-submission.md)

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

### Get submission documents

- [GET /submissions/{id}/documents](https://www.docuseal.com/docs/api/get-submission-documents.md)

This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned.

### Create a submission

- [POST /submissions](https://www.docuseal.com/docs/api/create-a-submission.md)

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](https://www.docuseal.com/guides/send-documents-for-signature-via-api.md)  
[Pre-fill PDF document form fields with API](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api.md)

### Create a submission from PDF

- [POST /submissions/pdf](https://www.docuseal.com/docs/api/create-a-submission-from-pdf.md)

The API endpoint provides the functionality to create one-off submission request from a PDF. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.pdf](https://www.docuseal.com/examples/fieldtags.pdf) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.  
**Related Guides**  
[Use embedded text field tags to create a fillable form](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form.md)

### Create a submission from DOCX

- [POST /submissions/docx](https://www.docuseal.com/docs/api/create-a-submission-from-docx.md)

The API endpoint provides functionality to create a one-off submission request from a DOCX file with dynamic content variables. Use `[[variable_name]]` text tags to define dynamic content variables in the document. See [https://www.docuseal.com/examples/demo_template.docx](https://www.docuseal.com/examples/demo_template.docx) for the specific text variable syntax, including dynamic content tables and lists. You can also use the `{{signature}}` field syntax to define fillable fields, as in a PDF.  
**Related Guides**  
[Use dynamic content variables in DOCX to create personalized documents](https://www.docuseal.com/guides/use-dynamic-content-variables-in-docx-to-create-personalized-documents.md)

### Create a submission from HTML

- [POST /submissions/html](https://www.docuseal.com/docs/api/create-a-submission-from-html.md)

This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.  
**Related Guides**  
[Create PDF document fillable form with HTML](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api.md)

### Update a submission

- [PUT /submissions/{id}](https://www.docuseal.com/docs/api/update-a-submission.md)

The API endpoint allows you to update a submission: change its name, expiration date, and archive or unarchive it.

### Archive a submission

- [DELETE /submissions/{id}](https://www.docuseal.com/docs/api/archive-a-submission.md)

The API endpoint allows you to archive a submission.

## Submitters

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

### List all submitters

- [GET /submitters](https://www.docuseal.com/docs/api/list-all-submitters.md)

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

### Get a submitter

- [GET /submitters/{id}](https://www.docuseal.com/docs/api/get-a-submitter.md)

The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values.

### Update a submitter

- [PUT /submitters/{id}](https://www.docuseal.com/docs/api/update-a-submitter.md)

The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.  
**Related Guides**  
[Automatically sign documents via API](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api#automatically-sign-documents-via-api)

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

### List all templates

- [GET /templates](https://www.docuseal.com/docs/api/list-all-templates.md)

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

### Get a template

- [GET /templates/{id}](https://www.docuseal.com/docs/api/get-a-template.md)

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

### Create a template from PDF

- [POST /templates/pdf](https://www.docuseal.com/docs/api/create-a-template-from-pdf.md)

The API endpoint provides the functionality to create a fillable document template for a PDF file. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.pdf](https://www.docuseal.com/examples/fieldtags.pdf) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.  
**Related Guides**  
[Use embedded text field tags to create a fillable form](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form.md)

### Create a template from DOCX

- [POST /templates/docx](https://www.docuseal.com/docs/api/create-a-template-from-docx.md)

The API endpoint provides the functionality to create a fillable document template for an existing Microsoft Word document. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.docx](https://www.docuseal.com/examples/fieldtags.docx) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.  
**Related Guides**  
[Use embedded text field tags to create a fillable form](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form.md)

### Create a template from HTML

- [POST /templates/html](https://www.docuseal.com/docs/api/create-a-template-from-html.md)

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](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api.md)

### Clone a template

- [POST /templates/{id}/clone](https://www.docuseal.com/docs/api/clone-a-template.md)

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

### Merge templates

- [POST /templates/merge](https://www.docuseal.com/docs/api/merge-templates.md)

The API endpoint allows you to merge multiple templates with documents and fields into a new combined template.

### Update a template

- [PUT /templates/{id}](https://www.docuseal.com/docs/api/update-a-template.md)

The API endpoint provides the functionality to move a document template to a different folder and update the name of the template.

### Update template documents

- [PUT /templates/{id}/documents](https://www.docuseal.com/docs/api/update-template-documents.md)

The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content.

### Archive a template

- [DELETE /templates/{id}](https://www.docuseal.com/docs/api/archive-a-template.md)

The API endpoint allows you to archive a document template.

## Webhooks

### Form Webhook

- [Example request](https://www.docuseal.com/docs/api/form-webhook.md)

During the form filling and signing process, 4 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 by one of the parties.
- **'form.declined'** event is triggered when a signer declines the submission.

 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](https://www.docuseal.com/guides/download-signed-documents.md)

### Submission Webhook

- [Example request](https://www.docuseal.com/docs/api/submission-webhook.md)

Get submission creation, completion, expiration, and archiving notifications using these events:

- **'submission.created'** event is triggered when the submission is created.
- **'submission.completed'** event is triggered when the submission is completed by all signing parties.
- **'submission.expired'** event is triggered when the submission expires.
- **'submission.archived'** event is triggered when the submission is archived.

### Template Webhook

- [Example request](https://www.docuseal.com/docs/api/template-webhook.md)

Get template creation and update notifications using these events:

- **'template.created'** is triggered when the template is created.
- **'template.updated'** is triggered when the template is updated.
- **'template.archived'** is triggered when the template is archived.