DocuSeal

Manage e-signature templates, submissions, and submitters with the CLI or AI agent.

## Agent Protocol

**Rules for agents:**
- Supply ALL required flags — the CLI will not prompt for missing parameters.
- Output is always JSON.
- Use `-d key=value` (bracket notation) or `-d '{"..": ".."}'` (JSON) for body and array parameters.

## Authentication

Set environment variables:
- `DOCUSEAL_API_KEY` — API key (required). Get yours at https://console.docuseal.com/api
- `DOCUSEAL_SERVER` — `global` (default), `europe`, or full URL for self-hosted (e.g. `https://docuseal.yourdomain.com`)

## Available Commands

| Command Group | What it does |
|---|---|
| `templates` | list, retrieve, update, archive, create-pdf, create-docx, create-html, clone, merge, update-documents |
| `submissions` | list, retrieve, archive, create, send-emails, create-pdf, create-docx, create-html, documents |
| `submitters` | list, retrieve, update |

Read the matching reference file for detailed flags and examples.

## Common Mistakes

| # | Mistake | Fix |
|---|---|---|
| 1 | **Forgetting `-d template_id=<id>` on `submissions create`** | `--template-id` is a flag; submitters and other body params go via `-d` |
| 2 | **Passing a plain file path as a URL** | `--file` accepts a local path; for remote files use `-d "documents[0][file]=https://..."` |
| 3 | **Expecting array params as comma-separated** | Arrays use bracket notation: `-d "template_ids[]=1"` `-d "template_ids[]=2"` |
| 4 | **Using `templates create-pdf` without a Pro plan** | Commands marked _(Pro)_ require a DocuSeal Pro subscription |
| 5 | **Sending to multiple recipients with `submissions create`** | Use `submissions send-emails --emails a@b.com,c@d.com` for bulk; `submissions create` is per-submitter |

## Security

The CLI accepts user-provided file paths, remote URLs (`documents[0][file]=https://...`), and HTML content as template input. This is by design — all content originates from the authenticated user and is sent directly to the DocuSeal API over HTTPS. The CLI does not fetch, render, or execute remote content locally; it passes references to the server for processing. No user input is interpolated into shell commands.

## Common Patterns

**List templates:**
```bash
docuseal templates list --q "NDA" --limit 20
```

**Create a template from a PDF and send for signing:**
```bash
docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal submissions send-emails --template-id 1001 --emails signer@example.com
```

**Create a submission with pre-filled fields (bracket notation):**
```bash
docuseal submissions create --template-id 1001 \
  -d "submitters[0][email]=john@acme.com" \
  -d "submitters[0][values][Company Name]=Acme Corp"
```

**Create a submission with pre-filled fields (JSON):**
```bash
docuseal submissions create --template-id 1001 \
  -d '{"submitters": [{"email": "john@acme.com", "values": {"Company Name": "Acme Corp"}}]}'
```

**Check signing status:**
```bash
docuseal submissions list --template-id 1001 --status pending
```

**Update a submitter:**
```bash
docuseal submitters update 201 --email new@acme.com --send-email
```

## When to Load References

- **Creating or managing templates** → [references/templates.md](references/templates.md)
- **Sending documents for signing or tracking status** → [references/submissions.md](references/submissions.md)
- **Using dynamic content variables in DOCX** → [references/docx-variables.md](references/docx-variables.md)
- **Embedding field tags in PDF/DOCX** → [references/field-tags.md](references/field-tags.md)
- **Writing HTML templates with field tags** → [references/html-fields.md](references/html-fields.md)
- **Listing or updating signers** → [references/submitters.md](references/submitters.md)

Add document signing to your app with embed components, REST API, SDKs, and webhooks.

## How References Are Organised

Reference files live in two subdirectories under `references/`:

- **`references/embed/`** — Embed UI components (signing forms, template builder). Each file is self-contained — load only the ones matching the user's stack.
- **`references/api/`** — REST API endpoints and webhooks. One file per endpoint/webhook with parameters, schemas, code examples, and response samples.

## Embed UI Components

| Component | Tag | Purpose | JWT |
|---|---|---|---|
| Signing Form | `<docuseal-form>` | Embed document signing UI into a page | optional |
| Form Builder | `<docuseal-builder>` | Embed a full template/document builder | **required** |

Each component ships in four frontend implementations: **JavaScript / React / Vue / Angular**.

### Signing Form (`<docuseal-form>`)

- JavaScript / HTML → [references/embed/signing-form-js.md](references/embed/signing-form-js.md)
- React → [references/embed/signing-form-react.md](references/embed/signing-form-react.md)
- Vue → [references/embed/signing-form-vue.md](references/embed/signing-form-vue.md)
- Angular → [references/embed/signing-form-angular.md](references/embed/signing-form-angular.md)
- Mobile (Android/iOS/React Native/Flutter via WebView) → [references/embed/signing-form-mobile-integration.md](references/embed/signing-form-mobile-integration.md)

### Form Builder (`<docuseal-builder>`)

- JavaScript / HTML → [references/embed/form-builder-js.md](references/embed/form-builder-js.md)
- React → [references/embed/form-builder-react.md](references/embed/form-builder-react.md)
- Vue → [references/embed/form-builder-vue.md](references/embed/form-builder-vue.md)
- Angular → [references/embed/form-builder-angular.md](references/embed/form-builder-angular.md)

After loading the main component reference, follow a link from its `## Guides` section for step-by-step walkthroughs.

### Cross-cutting

- JWT token generation — Form Builder (Node/TypeScript/Ruby/Python/PHP/Java/C#/Go) → [references/embed/form-builder-jwt-token.md](references/embed/form-builder-jwt-token.md)
- JWT token generation — Signing Form completed/preview mode → [references/embed/signing-form-completed-preview-jwt-token.md](references/embed/signing-form-completed-preview-jwt-token.md)
- EU Cloud / self-hosted `host` configuration — Signing Form → [references/embed/signing-form-hosts.md](references/embed/signing-form-hosts.md)
- EU Cloud / self-hosted `host` configuration — Form Builder → [references/embed/form-builder-hosts.md](references/embed/form-builder-hosts.md)
- Custom CSS theming — Signing Form (dark theme reference) → [references/embed/signing-form-custom-css.md](references/embed/signing-form-custom-css.md)
- Custom CSS theming — Form Builder (dark theme reference) → [references/embed/form-builder-custom-css.md](references/embed/form-builder-custom-css.md)

### Packages

| Framework | Package | CDN |
|---|---|---|
| JavaScript | — | `https://cdn.docuseal.com/js/form.js`, `https://cdn.docuseal.com/js/builder.js` |
| React | `@docuseal/react` | — |
| Vue | `@docuseal/vue` | — |
| Angular | `@docuseal/angular` | — |
| React Native | uses `react-native-webview` (no native SDK) | — |
| Flutter | uses `webview_flutter` (no native SDK) | — |

### Common Embed Mistakes

| # | Mistake | Fix |
|---|---|---|
| 1 | **Generating JWT in the browser** | JWT must be signed on the **backend** — the API key must never ship to the client. See [form-builder-jwt-token.md](references/embed/form-builder-jwt-token.md) / [signing-form-completed-preview-jwt-token.md](references/embed/signing-form-completed-preview-jwt-token.md). |
| 2 | **Passing the API key as `data-token`** | `data-token` is a JWT **signed with** the API key, not the key itself. |
| 3 | **Missing `host`/`data-host` on EU or self-hosted** | Set `data-host="cdn.docuseal.eu"` for EU Cloud or your own hostname for self-hosted. See [signing-form-hosts.md](references/embed/signing-form-hosts.md) / [form-builder-hosts.md](references/embed/form-builder-hosts.md). |
| 4 | **Confusing `/d/{slug}` vs `/s/{slug}`** | `/d/{slug}` is the template URL (single-party templates). `/s/{slug}` is an individual signer URL created via the `/submissions` API. |
| 5 | **Multi-party template via `data-src` URL** | Templates with multiple signing parties must be initiated via the `/submissions` API — the direct `/d/{slug}` URL only works for single-party templates. |
| 6 | **camelCase props in HTML** | The web component uses `data-*` kebab-case attributes. Only React/Vue/Angular use camelCase props. |
| 7 | **Expecting a native mobile SDK** | None exists. Embed via WebView — see [signing-form-mobile-integration.md](references/embed/signing-form-mobile-integration.md). |
| 8 | **Passing `customCss` as a stylesheet link** | `customCss` / `data-custom-css` takes a CSS string, not a URL. See [signing-form-custom-css.md](references/embed/signing-form-custom-css.md) / [form-builder-custom-css.md](references/embed/form-builder-custom-css.md). |

## REST API

### Authentication

All requests require an API key passed in the `X-Auth-Token` header:

```
X-Auth-Token: YOUR_API_KEY
```

Get your API key: https://console.docuseal.com/api

### Base URLs

| Environment | Base URL |
|---|---|
| Global Cloud | `https://api.docuseal.com` |
| EU Cloud | `https://api.docuseal.eu` |
| Self-hosted | `https://docuseal.yourdomain.com/api` |

### API Client SDKs

Official SDK libraries wrap the REST API and handle authentication, request building, and response parsing. **Prefer SDKs over raw HTTP when the user's language has one.**

| Language | Package | Install |
|---|---|---|
| JavaScript / TypeScript | `@docuseal/api` | `npm install @docuseal/api` |
| Python | `docuseal` | `pip install docuseal` |
| Ruby | `docuseal` | `gem install docuseal` |
| PHP | `docusealco/docuseal` | `composer require docusealco/docuseal` |

SDK usage examples are included in each endpoint reference file below (marked with "SDK" in the heading).

### Endpoints

**Templates**

  - `GET /templates` — [List all templates](references/api/list-all-templates.md)
  - `GET /templates/{id}` — [Get a template](references/api/get-a-template.md)
  - `DELETE /templates/{id}` — [Archive a template](references/api/archive-a-template.md)
  - `PUT /templates/{id}` — [Update a template](references/api/update-a-template.md)
  - `PUT /templates/{id}/documents` — [Update template documents](references/api/update-template-documents.md)
  - `POST /templates/{id}/clone` — [Clone a template](references/api/clone-a-template.md)
  - `POST /templates/html` — [Create a template from HTML](references/api/create-a-template-from-html.md)
  - `POST /templates/docx` — [Create a template from Word DOCX](references/api/create-a-template-from-word-docx.md)
  - `POST /templates/pdf` — [Create a template from PDF](references/api/create-a-template-from-pdf.md)
  - `POST /templates/merge` — [Merge templates](references/api/merge-templates.md)

**Submissions**

  - `GET /submissions` — [List all submissions](references/api/list-all-submissions.md)
  - `GET /submissions/{id}` — [Get a submission](references/api/get-a-submission.md)
  - `GET /submissions/{id}/documents` — [Get submission documents](references/api/get-submission-documents.md)
  - `DELETE /submissions/{id}` — [Archive a submission](references/api/archive-a-submission.md)
  - `POST /submissions/emails` — [Create submissions from emails](references/api/create-submissions-from-emails.md)
  - `POST /submissions/pdf` — [Create a submission from PDF](references/api/create-a-submission-from-pdf.md)
  - `POST /submissions/docx` — [Create a submission from DOCX](references/api/create-a-submission-from-docx.md)
  - `POST /submissions/html` — [Create a submission from HTML](references/api/create-a-submission-from-html.md)
  - `POST /submissions` — [Create a submission](references/api/create-a-submission.md)

**Submitters**

  - `GET /submitters/{id}` — [Get a submitter](references/api/get-a-submitter.md)
  - `PUT /submitters/{id}` — [Update a submitter](references/api/update-a-submitter.md)
  - `GET /submitters` — [List all submitters](references/api/list-all-submitters.md)

### Webhooks

- [Form Webhook](references/api/form-webhook.md)
- [Submission Webhook](references/api/submission-webhook.md)
- [Template Webhook](references/api/template-webhook.md)

Configure webhook URL: https://console.docuseal.com/webhooks

### Common API Patterns

1. **Send a document for signing:** create a template (or use existing) → `POST /submissions` with submitter emails → submitters receive signing links
2. **Embed signing in your app:** create submission with `send_email: false` → use returned `slug` with `<docuseal-form>` (see Embed UI Components above)
3. **Pre-fill and auto-sign:** `POST /submissions` with `fields[].default_value` and `completed: true`
4. **Track completion:** poll `GET /submissions/{id}` or configure webhooks for `form.completed`
5. **Download signed documents:** `GET /submissions/{id}/documents` returns PDF URLs

## Quick Decision Flow

1. **Embedding a component?** → Signing Form or Form Builder → load from `references/embed/`.
2. **Making API calls?** → Check if the user's language has an SDK (JS/TS, Python, Ruby, PHP) and prefer it over raw HTTP. Load the matching endpoint from `references/api/`.
3. **How-to question about embed?** Follow links from the component reference's `## Guides` section.
4. **Mobile?** Load [references/embed/signing-form-mobile-integration.md](references/embed/signing-form-mobile-integration.md).
5. **JWT needed?** Always for Form Builder — load [references/embed/form-builder-jwt-token.md](references/embed/form-builder-jwt-token.md). For Signing Form only when using `data-token` (preview/completed mode) — load [references/embed/signing-form-completed-preview-jwt-token.md](references/embed/signing-form-completed-preview-jwt-token.md).
6. **Not on `docuseal.com`?** Load [references/embed/signing-form-hosts.md](references/embed/signing-form-hosts.md) or [references/embed/form-builder-hosts.md](references/embed/form-builder-hosts.md) depending on the component.
7. **Custom theme?** Load [references/embed/signing-form-custom-css.md](references/embed/signing-form-custom-css.md) or [references/embed/form-builder-custom-css.md](references/embed/form-builder-custom-css.md) depending on the component.
8. **CLI commands?** Load the sibling `docuseal-cli` skill from this same repo.