docusealco 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
- React → references/embed/signing-form-react.md
- Vue → references/embed/signing-form-vue.md
- Angular → references/embed/signing-form-angular.md
- Mobile (Android/iOS/React Native/Flutter via WebView) → references/embed/signing-form-mobile-integration.md
Form Builder (<docuseal-builder>)
- JavaScript / HTML → references/embed/form-builder-js.md
- React → references/embed/form-builder-react.md
- Vue → references/embed/form-builder-vue.md
- Angular → 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
- JWT token generation — Signing Form completed/preview mode → references/embed/signing-form-completed-preview-jwt-token.md
- EU Cloud / self-hosted
hostconfiguration — Signing Form → references/embed/signing-form-hosts.md - EU Cloud / self-hosted
hostconfiguration — Form Builder → references/embed/form-builder-hosts.md - Custom CSS theming — Signing Form (dark theme reference) → references/embed/signing-form-custom-css.md
- Custom CSS theming — Form Builder (dark theme reference) → references/embed/form-builder-custom-css.md
- Signing Form security recommendations → references/embed/signing-form-security-recommendations.md
- Form Builder security recommendations → references/embed/form-builder-security-recommendations.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 / 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 / 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. |
| 8 | Passing customCss as a stylesheet link |
customCss / data-custom-css takes a CSS string, not a URL. See signing-form-custom-css.md / form-builder-custom-css.md. |
| 9 | Embedding signing forms behind enumerable URLs | DocuSeal slugs are random, but an embedding page like https://yourapp.com/contracts/123/sign lets an attacker iterate integer IDs to reach other users' signing forms. Put the DocuSeal slug or a UUID in your URL, or require auth on the embedding page. See signing-form-security-recommendations.md. |
| 10 | Exposing the Form Builder without auth | The page that renders <docuseal-builder> must be gated by your app's authentication. The JWT-issuing endpoint must verify the requesting user owns the template referenced by external_id. Otherwise any logged-in user can edit any template. See form-builder-security-recommendations.md. |
| 11 | Acting on client-side completed events |
Browser events can be forged. Drive state changes from form.completed webhooks with HMAC verification, not from <docuseal-form> JavaScript callbacks. See signing-form-security-recommendations.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 templatesGET /templates/{id}— Get a templateDELETE /templates/{id}— Archive a templatePUT /templates/{id}— Update a templatePUT /templates/{id}/documents— Update template documentsPOST /templates/{id}/clone— Clone a templatePOST /templates/html— Create a template from HTMLPOST /templates/docx— Create a template from DOCXPOST /templates/pdf— Create a template from PDFPOST /templates/merge— Merge templates
Submissions
GET /submissions— List all submissionsGET /submissions/{id}— Get a submissionGET /submissions/{id}/documents— Get submission documentsDELETE /submissions/{id}— Archive a submissionPUT /submissions/{id}— Update a submissionPOST /submissions/emails— Create submissions from emailsPOST /submissions/pdf— Create a submission from PDFPOST /submissions/docx— Create a submission from DOCXPOST /submissions/html— Create a submission from HTMLPOST /submissions— Create a submission
Submitters
GET /submitters/{id}— Get a submitterPUT /submitters/{id}— Update a submitterGET /submitters— List all submitters
Webhooks
- Form Webhook
- Submission Webhook
- Template Webhook
Configure webhook URL: https://console.docuseal.com/webhooks
Common API Patterns
- Send a document for signing: create a template (or use existing) →
POST /submissionswith submitter emails → submitters receive signing links - Embed signing in your app: create submission with
send_email: false→ use returnedslugwith<docuseal-form>(see Embed UI Components above) - Pre-fill and auto-sign:
POST /submissionswithfields[].default_valueandcompleted: true - Track completion: poll
GET /submissions/{id}or configure webhooks forform.completed - Download signed documents:
GET /submissions/{id}/documentsreturns PDF URLs
Quick Decision Flow
- Embedding a component? → Signing Form or Form Builder → load from
references/embed/. - 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/. - How-to question about embed? Follow links from the component reference's
## Guidessection. - Mobile? Load references/embed/signing-form-mobile-integration.md.
- JWT needed? Always for Form Builder — load 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. - Not on
docuseal.com? Load references/embed/signing-form-hosts.md or references/embed/form-builder-hosts.md depending on the component. - Custom theme? Load references/embed/signing-form-custom-css.md or references/embed/form-builder-custom-css.md depending on the component.
- Auth, URL handling, webhook verification, or any security-sensitive embedding? Load references/embed/signing-form-security-recommendations.md or references/embed/form-builder-security-recommendations.md depending on the component.
- CLI commands? Load the sibling
docuseal-cliskill from this same repo.