Skill: alexbturchyn/docuseal (version 1.0.5)

--- name: docuseal-cli description: > Manage DocuSeal e-signature workflows from the terminal via the DocuSeal CLI - create templates from PDF/DOCX/HTML, send documents for signing, track submissions, and update submitters. Use when the user wants to run DocuSeal commands in the shell, scripts, or CI/CD pipelines. Always load this skill before running `docuseal` commands. license: MIT metadata: author: DocuSeal version: "1.0.5" homepage: https://www.docuseal.com source: https://github.com/docusealco/docuseal-agent-skills openclaw: emoji: "📝" requires: env: - DOCUSEAL_API_KEY - DOCUSEAL_SERVER bins: - docuseal primaryEnv: DOCUSEAL_API_KEY install: - id: npm kind: npm package: docuseal bins: - docuseal label: Install DocuSeal CLI (npm) --- ## 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 [REDACTED_SECRET],[REDACTED_SECRET]` for bulk; `submissions create` is per-submitter | ## 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 [REDACTED_SECRET] ``` **Create a submission with pre-filled fields (bracket notation):** ```bash docuseal submissions create --template-id 1001 \ -d "submitters[0][email]=[REDACTED_SECRET]" \ -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": "[REDACTED_SECRET]", "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 [REDACTED_SECRET] --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)

path: references/html-fields.md
content: # HTML Field Tags

DocuSeal uses custom HTML tags to define fillable fields in templates. These tags can be used in `--html` or `--file` values for `templates create-html` and `submissions create-html` commands.

Full guide: https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api

## Available Tags

| Tag | Purpose |
|---|---|
| `<text-field>` | Text input |
| `<signature-field>` | Signature capture |
| `<date-field>` | Date picker |
| `<image-field>` | Image upload |
| `<initials-field>` | Initials capture |
| `<phone-field>` | Phone number input |
| `<stamp-field>` | Document stamp |
| `<file-field>` | File attachment |
| `<checkbox-field>` | Boolean checkbox |
| `<radio-field>` | Single option selection |
| `<select-field>` | Dropdown menu |
| `<multi-select-field>` | Multiple selection dropdown |
| `<payment-field>` | Payment processing |
| `<verification-field>` | Identity verification |

## Common Attributes

All tags support:

| Attribute | Description |
|---|---|
| `name` | Field identifier (required) |
| `role` | Signer role assignment |
| `default` | Pre-filled value |
| `required` | Required field, `true` by default |
| `readonly` | Prevent editing by signer |
| `title` | Display label |
| `description` | Help text shown to signer |
| `condition` | Conditional visibility, e.g. `"Status:active"` |
| `style` | CSS styling for field size and placement. Set `width` and `height` so the field renders on the page. |

**Important:** HTML field tags should usually include a `style` attribute with at least `width` and `height`. Without explicit dimensions, the rendered field can collapse and not appear where you expect in the document. For inline fields, `display: inline-block` is commonly used.

## Style Examples

Use `style=""` to control field size and layout:

```html
<text-field name="Full Name" role="Tenant" style="width: 160px; height: 20px; display: inline-block;"></text-field>
<signature-field name="Tenant Signature" role="Tenant" style="width: 160px; height: 80px; display: inline-block;"></signature-field>
```

## Text Formatting Attributes

| Attribute | Values |
|---|---|
| `font` | `Times`, `Helvetica`, `Courier` |
| `font-size` | Numeric value |
| `font-type` | `bold`, `italic`, `bold_italic` |
| `color` | `blue`, `red`, `black` (default) |
| `align` | `left`, `center`, `right` |
| `valign` | `top`, `center`, `bottom` |
| `mask` | `true` / `false` (hide sensitive data) |

## Type-Specific Attributes

**`<select-field>`, `<multi-select-field>`, `<radio-field>`:**

| Attribute | Description |
|---|---|
| `options` | Comma-separated list: `"opt1,opt2,opt3"` |

**`<date-field>`:**

| Attribute | Description |
|---|---|
| `min` / `max` | Min/max date |
| `format` | `DD/MM/YYYY` or `MM/DD/YYYY` |

**`<signature-field>`:**

| Attribute | Description |
|---|---|
| `format` | `drawn`, `typed`, `drawn_or_typed`, `upload` |

**`<payment-field>`:**

| Attribute | Description |
|---|---|
| `price` | Amount |
| `currency` | Currency code (e.g. `USD`) |

**`<verification-field>`:**

| Attribute | Description |
|---|---|
| `method` | `aes` or `qes` |

## Examples

**Simple contract:**
```html
<h1>Non-Disclosure Agreement</h1>
<p>This agreement is entered by
  <text-field name="Company Name" role="Company" style="width: 180px; height: 20px; display: inline-block;"></text-field>
  and
  <text-field name="Recipient Name" role="Recipient" style="width: 180px; height: 20px; display: inline-block;"></text-field>.
</p>

<p>Date:
  <date-field name="Date" format="MM/DD/YYYY" style="width: 110px; height: 20px; display: inline-block;"></date-field>
</p>

<p>Company signature:</p>
<signature-field name="Company Signature" role="Company" style="width: 180px; height: 80px; display: inline-block;"></signature-field>

<p>Recipient signature:</p>
<signature-field name="Recipient Signature" role="Recipient" style="width: 180px; height: 80px; display: inline-block;"></signature-field>
```

**Form with various field types:**
```html
<h2>Application Form</h2>
<p>Full Name: <text-field name="Full Name" required="true" style="width: 220px; height: 20px; display: inline-block;"></text-field></p>
<p>Phone: <phone-field name="Phone" style="width: 160px; height: 20px; display: inline-block;"></phone-field></p>
<p>Department: <select-field name="Department" options="Engineering,Sales,Marketing,HR" style="width: 180px; height: 24px; display: inline-block;"></select-field></p>
<p>Start Date: <date-field name="Start Date" min="2024-01-01" style="width: 120px; height: 20px; display: inline-block;"></date-field></p>
<p>Photo ID: <image-field name="Photo ID" style="width: 140px; height: 90px; display: inline-block;"></image-field></p>
<p>I agree to the terms: <checkbox-field name="Terms" required="true" style="width: 16px; height: 16px; display: inline-block;"></checkbox-field></p>
<signature-field name="Signature" style="width: 180px; height: 80px; display: inline-block;"></signature-field>
```

**Using with CLI:**
```bash
docuseal templates create-html --name "NDA" --html '<h1>NDA</h1>
<p>Party: <text-field name="Name" style="width: 180px; height: 20px; display: inline-block;"></text-field></p>
<signature-field name="Signature" style="width: 180px; height: 80px; display: inline-block;"></signature-field>'

docuseal templates create-html --name "NDA" --file nda.html

docuseal submissions create-html --file nda.html \
  -d "submitters[0][email]=[REDACTED_SECRET]"
```


path: references/templates.md
content: # Templates

## `docuseal templates list`

List all templates.

| Option | Description |
|---|---|
| `--q <value>` | Filter by name search |
| `--folder <value>` | Filter by folder name |
| `--slug <value>` | Filter by unique slug |
| `--external-id <value>` | Filter by external ID |
| `--archived` | Get only archived templates |
| `--active` | Get only active templates |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `--after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal templates list
docuseal templates list --folder Legal --limit 50
docuseal templates list --archived
```

---

## `docuseal templates retrieve <id>`

Get a template by ID.

```bash
docuseal templates retrieve 1001
```

---

## `docuseal templates update <id>`

Update a template.

| Option | Description |
|---|---|
| `--name <value>` | Template name |
| `--folder-name <value>` | Move to folder |
| `--archive` | Archive the template |
| `--unarchive` | Unarchive the template |

| Data param (`-d`) | Description |
|---|---|
| `roles[]` | Submitter role name |

```bash
docuseal templates update 1001 --name "NDA v2"
docuseal templates update 1001 --folder-name Contracts
docuseal templates update 1001 \
  -d "roles[]=Signer" \
  -d "roles[]=Reviewer"
docuseal templates update 1001 --unarchive
```

---

## `docuseal templates archive <id>`

Archive a template.

```bash
docuseal templates archive 1001
```

---

## `docuseal templates create-pdf` _(Pro)_

Create a template from a PDF file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local PDF file |
| `--name <value>` | Template name |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |
| `--flatten` | Remove PDF form fields |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags in the PDF |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path or URL |
| `documents[N][fields][M][name]` | Field name |
| `documents[N][fields][M][type]` | text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone |
| `documents[N][fields][M][role]` | Signer role name |
| `documents[N][fields][M][required]` | Required (true/false) |
| `documents[N][fields][M][title]` | Display title |
| `documents[N][fields][M][description]` | Display description (Markdown) |
| `documents[N][fields][M][areas][K][x/y/w/h]` | Position as fraction of page (0-1) |
| `documents[N][fields][M][areas][K][page]` | Page number (starts at 1) |
| `documents[N][fields][M][options][]` | Select/radio option values |

```bash
docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal templates create-pdf --file form.pdf --folder-name Legal
docuseal templates create-pdf \
  -d "documents[0][file]=./contract.pdf" \
  --name "NDA"
docuseal templates create-pdf \
  -d "documents[0][file]=https://example.com/contract.pdf" \
  --name "NDA"
docuseal templates create-pdf --file form.pdf \
  -d "documents[0][fields][0][name]=Name" \
  -d "documents[0][fields][0][type]=text"
```

---

## `docuseal templates create-docx` _(Pro)_

Create a template from a Word DOCX file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local DOCX file |
| `--name <value>` | Template name |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

Supports same `-d documents[N]...` data params as `create-pdf`.

```bash
docuseal templates create-docx --file template.docx --name "Contract"
docuseal templates create-docx \
  -d "documents[0][file]=./template.docx" \
  --name "Contract"
docuseal templates create-docx \
  -d "documents[0][file]=https://example.com/template.docx" \
  --name "Contract"
docuseal templates create-docx --file template.docx \
  -d "documents[0][fields][0][name]=Name" \
  -d "documents[0][fields][0][role]=Signer"
```

---

## `docuseal templates create-html` _(Pro)_

Create a template from HTML.

See [HTML Field Tags](html-fields.md) for supported tags, attributes, and `style` guidance.

| Option | Description |
|---|---|
| `--html <value>` | Inline HTML with field tags |
| `--file <path>` | Path to local HTML file |
| `--html-header <value>` | Header HTML (shown on every page) |
| `--html-footer <value>` | Footer HTML (shown on every page) |
| `--name <value>` | Template name |
| `--size <value>` | Page size: Letter (default), A4, Legal, A3, A5, A6, Tabloid, Ledger, A0, A1, A2 |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][html]` | HTML with field tags |
| `documents[N][name]` | Document name |

```bash
docuseal templates create-html \
  --html '<p><text-field name="Name"></text-field></p>' \
  --name "Simple"
docuseal templates create-html \
  --file template.html \
  --name "Contract"
docuseal templates create-html \
  -d 'documents[0][html]=<p><text-field name="Name"></text-field></p>' \
  -d "documents[0][name]=Page 1"
```

---

## `docuseal templates clone <id>`

Clone a template.

| Option | Description |
|---|---|
| `--name <value>` | Name for the clone (default: original name + "(Clone)") |
| `--folder-name <value>` | Folder to clone into |
| `--external-id <value>` | App-specific unique key |

```bash
docuseal templates clone 1001
docuseal templates clone 1001 --name "NDA Copy"
```

---

## `docuseal templates merge` _(Pro)_

Merge multiple templates into one.

| Option | Description |
|---|---|
| `--name <value>` | Name for the merged template |
| `--folder-name <value>` | Folder to place merged template |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to include (required, repeatable) |
| `roles[]` | Submitter role name |

```bash
docuseal templates merge \
  -d "template_ids[]=1001" \
  -d "template_ids[]=1002"
docuseal templates merge \
  -d "template_ids[]=1001" \
  -d "template_ids[]=1002" \
  --name "Combined"
```

---

## `docuseal templates update-documents <id>` _(Pro)_

Update documents within an existing template.

| Option | Description |
|---|---|
| `--merge` | Merge all docs into a single PDF |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][html]` | HTML template with field tags |
| `documents[N][position]` | Position in template |
| `documents[N][replace]` | Replace existing document (true/false) |
| `documents[N][remove]` | Remove document (true/false) |

```bash
docuseal templates update-documents 1001 \
  -d "documents[0][file]=./contract.pdf"
docuseal templates update-documents 1001 \
  -d "documents[0][file]=https://example.com/doc.pdf"
docuseal templates update-documents 1001 \
  -d "documents[0][file]=https://example.com/doc.pdf" \
  -d "documents[0][name]=New Doc"
```


path: references/field-tags.md
content: # PDF / DOCX Field Tags

DocuSeal uses embedded text tags in PDF and DOCX documents to define fillable fields. Tags are placed directly in the document text and are automatically detected when uploaded via `templates create-pdf`, `templates create-docx`, `submissions create-pdf`, or `submissions create-docx`.

Full guide: https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form

## Syntax

Tags use double curly braces. Attributes are separated by semicolons:

```
{{Field Name}}
{{Field Name;type=signature}}
{{Field Name;type=date;role=First Party;required=true}}
```

## Field Types

| Type | Description |
|---|---|
| `text` | Text input (default) |
| `signature` | Signature capture |
| `initials` | Initials capture |
| `date` | Date picker |
| `datenow` | Auto-filled signing date (read-only) |
| `image` | Image upload |
| `file` | File upload |
| `payment` | Payment field |
| `stamp` | Document stamp |
| `select` | Dropdown menu |
| `checkbox` | Boolean checkbox |
| `multiple` | Multiple selection |
| `radio` | Radio button |
| `phone` | Phone number (2FA) |
| `verification` | Identity verification |
| `kba` | Knowledge-based authentication |

## Attributes

| Attribute | Description |
|---|---|
| `name` | Field name (the text before the first `;`) |
| `type` | Field type (default: `text`) |
| `role` | Signer role for multi-party signing |
| `default` | Pre-filled value |
| `required` | Required field (`true` by default) |
| `readonly` | Prevent editing (`false` by default) |
| `title` | Display label in signing UI |
| `description` | Help text in signing UI |
| `options` | Comma-separated values for select/radio/multiple |
| `option` | Single option value for radio buttons |
| `condition` | Conditional visibility: `FieldName:value` |
| `width` | Width in pixels |
| `height` | Height in pixels |
| `hidden` | Hide field (`true`/`false`) |
| `mask` | Mask sensitive data (`true`/`false`) |

## Text Formatting

| Attribute | Values |
|---|---|
| `font` | `Times`, `Helvetica`, `Courier` |
| `font_size` | Numeric value |
| `font_type` | `bold`, `italic`, `bold_italic` |
| `color` | `blue`, `red`, `black` (default) |
| `align` | `left`, `center`, `right` |
| `valign` | `top`, `center`, `bottom` |

## Type-Specific Attributes

| Attribute | Applies to | Values |
|---|---|---|
| `format` | date | `DD/MM/YYYY`, `MM/DD/YYYY` (default) |
| `format` | signature | `drawn`, `typed`, `drawn_or_typed` (default), `upload` |
| `format` | number | `usd`, `eur`, `gbp` |
| `min` / `max` | date, number | Min/max allowed value |
| `method` | verification | `aes`, `qes` |

## Examples

**Basic fields:**
```
{{Full Name}}
{{Email;title=Email Address}}
{{Sign;type=signature}}
{{Date;type=date;format=DD/MM/YYYY}}
{{Today;type=datenow}}
```

**Multi-role signing:**
```
{{Landlord Name;role=Landlord}}
{{Landlord Sign;type=signature;role=Landlord}}
{{Tenant Name;role=Tenant}}
{{Tenant Sign;type=signature;role=Tenant}}
```

**Selection fields:**
```
{{Department;type=select;options=Engineering,Sales,Marketing,HR}}
{{Priority;type=radio;option=Low}}
{{Priority;type=radio;option=Medium}}
{{Priority;type=radio;option=High}}
{{type=checkbox}} I agree to the terms
```

**Conditional fields:**
```
{{Agree;type=checkbox}}
{{Details;condition=Agree:true}}
```

**Using with CLI:**
```bash
docuseal templates create-pdf --file contract.pdf --name "Contract"
docuseal templates create-docx --file contract.docx --name "Contract"
docuseal submissions create-pdf --file contract.pdf \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d "submitters[0][role]=Tenant"
```

## Resources

- Example PDF with field tags: https://www.docuseal.com/examples/fieldtags.pdf


path: references/submissions.md
content: # Submissions

## `docuseal submissions list`

List all submissions.

| Option | Description |
|---|---|
| `--template-id <value>` | Filter by template ID |
| `--status <value>` | pending, completed, declined, expired |
| `--q <value>` | Filter by submitter name, email, or phone |
| `--slug <value>` | Filter by unique slug |
| `--template-folder <value>` | Filter by template folder name |
| `--archived` | Get only archived submissions |
| `--active` | Get only active submissions |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `-a, --after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal submissions list
docuseal submissions list --status pending
docuseal submissions list \
  --template-id 1001 \
  --limit 50
docuseal submissions list --q "[REDACTED_SECRET]"
```

---

## `docuseal submissions retrieve <id>`

Get a submission by ID.

```bash
docuseal submissions retrieve 502
```

---

## `docuseal submissions archive <id>`

Archive a submission.

```bash
docuseal submissions archive 502
```

---

## `docuseal submissions create`

Create a submission from an existing template.

| Option | Description |
|---|---|
| `--template-id <value>` | Template ID (required) |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--order <value>` | `preserved` (default) or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `variables[key]` | Template variable |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |
| `submitters[N][name]` | Full name |
| `submitters[N][role]` | Role name (e.g. "First Party") |
| `submitters[N][email]` | Email address (required) |
| `submitters[N][phone]` | Phone in E.164 format (e.g. +1234567890) |
| `submitters[N][values][fieldName]` | Pre-filled field value |
| `submitters[N][external_id]` | App-specific ID |
| `submitters[N][completed]` | Mark as completed (true/false) |
| `submitters[N][metadata][key]` | Submitter metadata |
| `submitters[N][send_email]` | Send email (true/false) |
| `submitters[N][send_sms]` | Send SMS (true/false) |
| `submitters[N][reply_to]` | Reply-To email |
| `submitters[N][completed_redirect_url]` | Redirect URL after completion |
| `submitters[N][order]` | Signing order (0, 1, 2...) |
| `submitters[N][require_phone_2fa]` | Require phone 2FA (true/false) |
| `submitters[N][require_email_2fa]` | Require email 2FA (true/false) |
| `submitters[N][message][subject]` | Per-submitter email subject |
| `submitters[N][message][body]` | Per-submitter email body |
| `submitters[N][fields][M][name]` | Field name (required) |
| `submitters[N][fields][M][default_value]` | Default value |
| `submitters[N][fields][M][readonly]` | Read-only (true/false) |
| `submitters[N][fields][M][required]` | Required (true/false) |
| `submitters[N][roles][]` | Merge multiple roles |

```bash
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d "submitters[1][email]=[REDACTED_SECRET]"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d "submitters[0][role]=Signer"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  --no-send-email
```

---

## `docuseal submissions send-emails`

Send a template to multiple recipients by email — creates one submission per recipient.

| Option | Description |
|---|---|
| `--template-id <value>` | Template ID (required) |
| `--emails <value>` | Comma-separated list of email addresses |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |

| Data param (`-d`) | Description |
|---|---|
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |

```bash
docuseal submissions send-emails \
  --template-id 1001 \
  --emails [REDACTED_SECRET],[REDACTED_SECRET]
docuseal submissions send-emails \
  --template-id 1001 \
  --emails [REDACTED_SECRET] \
  -d "message[subject]=Please sign" \
  -d "message[body]=Hello"
```

---

## `docuseal submissions create-pdf` _(Pro)_

Create a submission directly from a PDF file (no pre-existing template needed).

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local PDF file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--order <value>` | `preserved` or `random` |
| `--flatten` | Remove PDF form fields |
| `--merge-documents` | Merge into single PDF |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags in the PDF |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][position]` | Position in template |
| `submitters[N][name]` | Full name |
| `submitters[N][role]` | Role name |
| `submitters[N][email]` | Email address (required) |
| `submitters[N][phone]` | Phone (E.164) |
| `submitters[N][values][fieldName]` | Pre-filled field value |
| `submitters[N][external_id]` | App-specific ID |
| `submitters[N][completed]` | Mark as completed (true/false) |
| `submitters[N][metadata][key]` | Submitter metadata |
| `submitters[N][send_email]` | Send email (true/false) |
| `submitters[N][send_sms]` | Send SMS (true/false) |
| `submitters[N][reply_to]` | Reply-To email |
| `submitters[N][completed_redirect_url]` | Redirect URL after completion |
| `submitters[N][order]` | Signing order (0, 1, 2...) |
| `submitters[N][require_phone_2fa]` | Require phone 2FA (true/false) |
| `submitters[N][require_email_2fa]` | Require email 2FA (true/false) |
| `submitters[N][invite_by]` | Role name of inviting party |
| `submitters[N][fields][M][name]` | Field name (required) |
| `submitters[N][fields][M][default_value]` | Default value |
| `submitters[N][fields][M][readonly]` | Read-only (true/false) |
| `submitters[N][fields][M][required]` | Required (true/false) |
| `submitters[N][roles][]` | Merge multiple roles |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |

```bash
docuseal submissions create-pdf \
  --file doc.pdf \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create-pdf \
  -d "documents[0][file]=./doc.pdf" \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create-pdf \
  -d "documents[0][file]=https://example.com/doc.pdf" \
  -d "submitters[0][email]=[REDACTED_SECRET]"
```

---

## `docuseal submissions create-docx` _(Pro)_

Create a submission directly from a DOCX file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax. See [DOCX Variables](docx-variables.md) for DOCX-specific variables, loops, and conditional content.

| Option | Description |
|---|---|
| `--file <path>` | Path to local DOCX file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--merge-documents` | Merge into single PDF |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags |
| `--order <value>` | `preserved` or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `variables[key]` | Template variable |
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][position]` | Position in template |

Supports same `-d submitters[N]...` and `message` data params as `submissions create-pdf`.

```bash
docuseal submissions create-docx \
  --file doc.docx \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create-docx \
  -d "documents[0][file]=./doc.docx" \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create-docx \
  -d "documents[0][file]=https://example.com/doc.docx" \
  -d "submitters[0][email]=[REDACTED_SECRET]"
```

---

## `docuseal submissions create-html` _(Pro)_

Create a submission directly from HTML.

See [HTML Field Tags](html-fields.md) for supported tags, attributes, and `style` guidance.

| Option | Description |
|---|---|
| `--file <path>` | Path to local HTML file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--merge-documents` | Merge into single PDF |
| `--order <value>` | `preserved` or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][name]` | Document name |
| `documents[N][html]` | HTML template with field tags |
| `documents[N][html_header]` | HTML header for every page |
| `documents[N][html_footer]` | HTML footer for every page |
| `documents[N][size]` | Page size (Letter, A4, ...) |
| `documents[N][position]` | Position in template |

Supports same `-d submitters[N]...` and `message` data params as `submissions create-pdf`.

```bash
docuseal submissions create-html \
  --file template.html \
  -d "submitters[0][email]=[REDACTED_SECRET]"
docuseal submissions create-html \
  -d 'documents[0][html]=<p><text-field name="Name"></text-field></p>' \
  -d "submitters[0][email]=[REDACTED_SECRET]"
```

---

## `docuseal submissions documents <id>`

Get documents for a submission.

| Option | Description |
|---|---|
| `--merge` | Merge all documents into a single PDF |

```bash
docuseal submissions documents 502
docuseal submissions documents 502 --merge
```


path: references/submitters.md
content: # Submitters

## `docuseal submitters list`

List all submitters.

| Option | Description |
|---|---|
| `--submission-id <value>` | Filter by submission ID |
| `--q <value>` | Filter by name, email, or phone partial match |
| `--slug <value>` | Filter by unique slug |
| `--external-id <value>` | Filter by external ID |
| `--completed-after <value>` | Filter by completion date (after) |
| `--completed-before <value>` | Filter by completion date (before) |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `-a, --after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal submitters list
docuseal submitters list --submission-id 502
docuseal submitters list --q "[REDACTED_SECRET]"
```

---

## `docuseal submitters retrieve <id>`

Get a submitter by ID.

```bash
docuseal submitters retrieve 201
```

---

## `docuseal submitters update <id>`

Update a submitter — change contact info, pre-fill fields, re-send notifications, or mark as completed.

| Option | Description |
|---|---|
| `--name <value>` | Full name |
| `--email <value>` | Email address |
| `--phone <value>` | Phone in E.164 format (e.g. +1234567890) |
| `--external-id <value>` | App-specific unique key |
| `--send-email` | Re-send signature request email |
| `--send-sms` | Re-send via SMS |
| `--completed` | Mark as completed (auto-signed) |
| `--reply-to <value>` | Reply-To email address |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--require-phone-2fa` | Require phone 2FA |
| `--require-email-2fa` | Require email 2FA |

| Data param (`-d`) | Description |
|---|---|
| `values[fieldName]` | Pre-filled field value |
| `metadata[key]` | Submitter metadata |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |
| `fields[N][name]` | Field name (required) |
| `fields[N][default_value]` | Default value |
| `fields[N][readonly]` | Read-only (true/false) |
| `fields[N][required]` | Required (true/false) |

```bash
docuseal submitters update 201 --email [REDACTED_SECRET]
docuseal submitters update 201 --completed
docuseal submitters update 201 \
  -d "values[First Name]=John" \
  -d "metadata[department]=Sales"
```


path: references/docx-variables.md
content: # DOCX Dynamic Content Variables

DocuSeal supports dynamic content variables in DOCX templates. Variables are replaced with provided values when creating a submission via `submissions create-docx` using the `-d "variables[key]=value"` syntax.

Full guide: https://www.docuseal.com/guides/use-dynamic-content-variables-in-docx-to-create-personalized-documents

## Syntax

Variables use double-bracket notation: `[[variable_name]]`

## Simple Variables

```
[[signer_name]]
[[company_name]]
[[contract_date]]
```

Replaced with the corresponding value passed via `variables`.

## Conditional Logic

**If:**
```
[[if:is_vip]] Thank you for being a valued VIP customer! [[end]]
```

**If/else:**
```
[[if:is_vip]] Thank you for being a valued VIP customer! [[else]] Thank you for being our customer. [[end:is_vip]]
```

The condition variable is a boolean.

## Loops

Iterate over arrays using `[[for:array_name]]`:

```
[[for:items]] - [[item.name]] ([[item.quantity]]) [[end]]
```

Table rows:
```
[[for:invoices]]
| [[invoice.name]] | [[invoice.quantity]] | [[invoice.price]] | [[invoice.total]] |
[[end]]
```

Inside the loop, access properties via singular dot notation: `items` array → `item.name`.

## HTML Content Variables

Variable values can contain styled HTML rendered directly in the DOCX:

**Paragraphs:**
```html
<p><b style="color: #1976D2; text-decoration: underline;">Bold blue text</b> normal text.</p>
```

**Lists:**
```html
<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>
```

**Tables:**
```html
<table border="1" style="border-collapse: collapse;">
  <tr><th style="padding: 8px;"><b>Item</b></th><th><b>Price</b></th></tr>
  <tr><td style="padding: 8px;">Widget</td><td>$50</td></tr>
</table>
```

**Links:**
```html
<a href="https://example.com" style="color: #1976D2;">Example Link</a>
```

## Using with CLI

```bash
# Simple variables
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d "variables[signer_name]=John Doe" \
  -d "variables[company_name]=Acme Corp"

# Boolean for conditionals
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d "variables[is_vip]=true"

# HTML content
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=[REDACTED_SECRET]" \
  -d 'variables[description]=<p><b>Important</b> details here.</p>'
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)