From e98432d7e498bb33efb6776c43d2964682c232c1 Mon Sep 17 00:00:00 2001 From: Alex Turchyn Date: Mon, 15 Dec 2025 10:24:23 +0200 Subject: [PATCH] update docs --- docs/api/csharp.md | 4698 +++++++++--------- docs/api/go.md | 5464 ++++++++++----------- docs/api/java.md | 4676 +++++++++--------- docs/api/javascript.md | 4925 +++++++++---------- docs/api/nodejs.md | 5357 ++++++++++---------- docs/api/php.md | 4893 +++++++++--------- docs/api/python.md | 4937 +++++++++---------- docs/api/ruby.md | 4939 +++++++++---------- docs/api/shell.md | 4688 +++++++++--------- docs/api/typescript.md | 4925 +++++++++---------- docs/embedding/form-builder-angular.md | 17 +- docs/embedding/form-builder-javascript.md | 17 +- docs/embedding/form-builder-react.md | 17 +- docs/embedding/form-builder-vue.md | 17 +- docs/embedding/signing-form-angular.md | 2 +- docs/embedding/signing-form-javascript.md | 2 +- docs/embedding/signing-form-react.md | 2 +- docs/embedding/signing-form-vue.md | 2 +- docs/openapi.json | 539 +- docs/webhooks/submission-webhook.md | 4 + 20 files changed, 24109 insertions(+), 26012 deletions(-) diff --git a/docs/api/csharp.md b/docs/api/csharp.md index 2d4d56a7..a5668413 100644 --- a/docs/api/csharp.md +++ b/docs/api/csharp.md @@ -1,257 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```csharp -var client = new RestClient("https://api.docuseal.com/templates"); -var request = new RestRequest("", Method.Get); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001"); -var request = new RestRequest("", Method.Get); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001"); -var request = new RestRequest("", Method.Delete); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001"); -var request = new RestRequest("", Method.Put); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -368,6 +114,82 @@ var response = client.Execute(request); } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/1001"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/1001/documents"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -532,6 +354,11 @@ var response = client.Execute(request); "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -683,6 +510,15 @@ var response = client.Execute(request); ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -736,6 +572,13 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -760,14 +603,17 @@ var response = client.Execute(request); } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/1001"); -var request = new RestRequest("", Method.Get); +var client = new RestClient("https://api.docuseal.com/submissions/pdf"); +var request = new RestRequest("", Method.Post); request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -781,20 +627,1462 @@ var response = client.Execute(request); "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } - ] + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/docx"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/html"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -836,12 +2124,12 @@ var response = client.Execute(request); } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/1001/documents"); +var client = new RestClient("https://api.docuseal.com/submitters"); var request = new RestRequest("", Method.Get); request.AddHeader("X-Auth-Token", "API_KEY"); var response = client.Execute(request); @@ -855,98 +2143,101 @@ var response = client.Execute(request); } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```csharp -var client = new RestClient("https://api.docuseal.com/submissions/emails"); -var request = new RestRequest("", Method.Post); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"template_id\":1000001,\"emails\":\"hi@docuseal.com, example@docuseal.com\"}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1226,6 +2517,15 @@ var response = client.Execute(request); ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1279,6 +2579,13 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1293,12 +2600,12 @@ var response = client.Execute(request); } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```csharp -var client = new RestClient("https://api.docuseal.com/submitters"); +var client = new RestClient("https://api.docuseal.com/templates"); var request = new RestRequest("", Method.Get); request.AddHeader("X-Auth-Token", "API_KEY"); var response = client.Execute(request); @@ -1312,20 +2619,11 @@ var response = client.Execute(request); } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1333,7 +2631,7 @@ var response = client.Execute(request); "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1342,30 +2640,8 @@ var response = client.Execute(request); "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1374,7 +2650,25 @@ var response = client.Execute(request); "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1383,7 +2677,7 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1392,7 +2686,7 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1401,22 +2695,20 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001/documents"); -var request = new RestRequest("", Method.Put); +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Get); request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"documents\":[{\"file\":\"string\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -1430,8 +2722,8 @@ var response = client.Execute(request); "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", + "summary": "Get a template", + "operationId": "getTemplate", "parameters": [ { "name": "id", @@ -1440,78 +2732,24 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The unique identifier of the documents template.", + "description": "The unique identifier of the document template.", "example": 1000001 } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } + ] } ``` -### Clone a template +### Create a template from PDF + +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 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 -The API endpoint allows you to clone existing template into a new template. ```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001/clone"); +var client = new RestClient("https://api.docuseal.com/templates/pdf"); var request = new RestRequest("", Method.Post); request.AddHeader("X-Auth-Token", "API_KEY"); request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Cloned Template\"}", ParameterType.RequestBody); +request.AddParameter("application/json", "{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -1525,73 +2763,8 @@ var response = client.Execute(request); "tags": [ "Templates" ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/html"); -var request = new RestRequest("", Method.Post); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\",\"name\":\"Test Template\"}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1600,55 +2773,23 @@ var response = client.Execute(request); "schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1656,25 +2797,287 @@ var response = client.Execute(request); }, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1789,7 +3192,8 @@ var response = client.Execute(request); "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1927,6 +3331,15 @@ var response = client.Execute(request); ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1980,6 +3393,13 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1997,17 +3417,16 @@ var response = client.Execute(request); } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```csharp -var client = new RestClient("https://api.docuseal.com/templates/pdf"); +var client = new RestClient("https://api.docuseal.com/templates/html"); var request = new RestRequest("", Method.Post); request.AddHeader("X-Auth-Token", "API_KEY"); request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}", ParameterType.RequestBody); +request.AddParameter("application/json", "{\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\",\"name\":\"Test Template\"}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -2021,8 +3440,8 @@ var response = client.Execute(request); "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2031,246 +3450,78 @@ var response = client.Execute(request); "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2283,6 +3534,71 @@ var response = client.Execute(request); } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/1000001/clone"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Cloned Template\"}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2367,994 +3683,16 @@ var response = client.Execute(request); } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/pdf"); -var request = new RestRequest("", Method.Post); +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Put); request.AddHeader("X-Auth-Token", "API_KEY"); request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```csharp -var client = new RestClient("https://api.docuseal.com/submissions/html"); -var request = new RestRequest("", Method.Post); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/pdf"); -var request = new RestRequest("", Method.Post); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}", ParameterType.RequestBody); +request.AddParameter("application/json", "{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -3368,304 +3706,51 @@ var response = client.Execute(request); "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "The name of the template", + "example": "New Document Name" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { + "roles": { "type": "array", + "description": "An array of submitter role names to update the template with.", "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3675,16 +3760,16 @@ var response = client.Execute(request); } ``` -### Create a submission from DOCX +### Update template documents -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/docx"); -var request = new RestRequest("", Method.Post); +var client = new RestClient("https://api.docuseal.com/templates/1000001/documents"); +var request = new RestRequest("", Method.Put); request.AddHeader("X-Auth-Token", "API_KEY"); request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); +request.AddParameter("application/json", "{\"documents\":[{\"file\":\"string\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -3696,406 +3781,71 @@ var response = client.Execute(request); } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." }, "position": { "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "merge": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -4105,3 +3855,41 @@ var response = client.Execute(request); } ``` +### Archive a template + +The API endpoint allows you to archive a document template. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Delete); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + diff --git a/docs/api/go.md b/docs/api/go.md index c0622ea8..a141ac3a 100644 --- a/docs/api/go.md +++ b/docs/api/go.md @@ -1,343 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates" - - req, _ := http.NewRequest("GET", url, nil) - - req.Header.Add("X-Auth-Token", "API_KEY") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/1000001" - - req, _ := http.NewRequest("GET", url, nil) - - req.Header.Add("X-Auth-Token", "API_KEY") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/1000001" - - req, _ := http.NewRequest("DELETE", url, nil) - - req.Header.Add("X-Auth-Token", "API_KEY") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/1000001" - - payload := strings.NewReader("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") - - req, _ := http.NewRequest("PUT", url, payload) - - req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -475,6 +135,124 @@ func main() { } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/1001" + + req, _ := http.NewRequest("GET", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/1001/documents" + + req, _ := http.NewRequest("GET", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -662,6 +440,11 @@ func main() { "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -813,6 +596,15 @@ func main() { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -866,6 +658,13 @@ func main() { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -890,26 +689,31 @@ func main() { } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```go package main import ( "fmt" + "strings" "net/http" "io" ) func main() { - url := "https://api.docuseal.com/submissions/1001" + url := "https://api.docuseal.com/submissions/pdf" - req, _ := http.NewRequest("GET", url, nil) + payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + + req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") res, _ := http.DefaultClient.Do(req) @@ -932,20 +736,1508 @@ func main() { "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } - ] + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/docx" + + payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/html" + + payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -1008,9 +2300,9 @@ func main() { } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```go package main @@ -1023,7 +2315,7 @@ import ( func main() { - url := "https://api.docuseal.com/submissions/1001/documents" + url := "https://api.docuseal.com/submitters" req, _ := http.NewRequest("GET", url, nil) @@ -1048,121 +2340,101 @@ func main() { } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submissions/emails" - - payload := strings.NewReader("{\"template_id\":1000001,\"emails\":\"hi@docuseal.com, example@docuseal.com\"}") - - req, _ := http.NewRequest("POST", url, payload) - - req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1486,6 +2758,15 @@ func main() { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1539,6 +2820,13 @@ func main() { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1553,9 +2841,9 @@ func main() { } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```go package main @@ -1568,7 +2856,7 @@ import ( func main() { - url := "https://api.docuseal.com/submitters" + url := "https://api.docuseal.com/templates" req, _ := http.NewRequest("GET", url, nil) @@ -1593,20 +2881,11 @@ func main() { } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1614,7 +2893,7 @@ func main() { "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1623,30 +2902,8 @@ func main() { "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1655,7 +2912,25 @@ func main() { "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1664,7 +2939,7 @@ func main() { "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1673,7 +2948,7 @@ func main() { "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1682,36 +2957,32 @@ func main() { "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```go package main import ( "fmt" - "strings" "net/http" "io" ) func main() { - url := "https://api.docuseal.com/templates/1000001/documents" + url := "https://api.docuseal.com/templates/1000001" - payload := strings.NewReader("{\"documents\":[{\"file\":\"string\"}]}") - - req, _ := http.NewRequest("PUT", url, payload) + req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") res, _ := http.DefaultClient.Do(req) @@ -1734,8 +3005,8 @@ func main() { "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", + "summary": "Get a template", + "operationId": "getTemplate", "parameters": [ { "name": "id", @@ -1744,71 +3015,17 @@ func main() { "schema": { "type": "integer" }, - "description": "The unique identifier of the documents template.", + "description": "The unique identifier of the document template.", "example": 1000001 } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } + ] } ``` -### Clone a template +### Create a template from PDF + +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 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 -The API endpoint allows you to clone existing template into a new template. ```go package main @@ -1822,9 +3039,9 @@ import ( func main() { - url := "https://api.docuseal.com/templates/1000001/clone" + url := "https://api.docuseal.com/templates/pdf" - payload := strings.NewReader("{\"name\":\"Cloned Template\"}") + payload := strings.NewReader("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") req, _ := http.NewRequest("POST", url, payload) @@ -1852,39 +3069,674 @@ func main() { "tags": [ "Templates" ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "documents" + ], "properties": { "name": { "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be cloned." + "description": "The folder's name to which the template should be created." }, "external_id": { "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a template from Word DOCX + +The API endpoint provides the functionality to create a fillable document template for 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 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 + + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/docx" + + payload := strings.NewReader("{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test DOCX" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new document.", + "example": "unique-key" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } } } } @@ -2034,10 +3886,9 @@ func main() { } ``` -### Create a template from Word DOCX - -The API endpoint provides the functionality to create a fillable document template for 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 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 +### Clone a template +The API endpoint allows you to clone existing template into a new template. ```go package main @@ -2051,9 +3902,9 @@ import ( func main() { - url := "https://api.docuseal.com/templates/docx" + url := "https://api.docuseal.com/templates/1000001/clone" - payload := strings.NewReader("{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}") + payload := strings.NewReader("{\"name\":\"Cloned Template\"}") req, _ := http.NewRequest("POST", url, payload) @@ -2081,595 +3932,39 @@ func main() { "tags": [ "Templates" ], - "summary": "Create a template from Word DOCX", - "operationId": "createTemplateFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test DOCX" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new document.", - "example": "unique-key" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" - }, - "fields": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1." - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 - - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/pdf" - - payload := strings.NewReader("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") - - req, _ := http.NewRequest("POST", url, payload) - - req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ { - "AuthToken": [] + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 } ], - "tags": [ - "Templates" - ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be cloned." }, "external_id": { "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } + "description": "Your application-specific unique string key to identify this template within your app." } } } @@ -2786,10 +4081,9 @@ func main() { } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```go package main @@ -2803,1034 +4097,11 @@ import ( func main() { - url := "https://api.docuseal.com/submissions/pdf" + url := "https://api.docuseal.com/templates/1000001" - payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + payload := strings.NewReader("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") - req, _ := http.NewRequest("POST", url, payload) - - req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submissions/html" - - payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") - - req, _ := http.NewRequest("POST", url, payload) - - req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - -} -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/pdf" - - payload := strings.NewReader("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") - - req, _ := http.NewRequest("POST", url, payload) + req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("X-Auth-Token", "API_KEY") req.Header.Add("content-type", "application/json") @@ -3856,304 +4127,51 @@ func main() { "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "The name of the template", + "example": "New Document Name" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { + "roles": { "type": "array", + "description": "An array of submitter role names to update the template with.", "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -4163,9 +4181,9 @@ func main() { } ``` -### Create a submission from DOCX +### Update template documents -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```go package main @@ -4179,11 +4197,11 @@ import ( func main() { - url := "https://api.docuseal.com/submissions/docx" + url := "https://api.docuseal.com/templates/1000001/documents" - payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + payload := strings.NewReader("{\"documents\":[{\"file\":\"string\"}]}") - req, _ := http.NewRequest("POST", url, payload) + req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("X-Auth-Token", "API_KEY") req.Header.Add("content-type", "application/json") @@ -4207,406 +4225,71 @@ func main() { } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." }, "position": { "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "merge": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -4616,3 +4299,62 @@ func main() { } ``` +### Archive a template + +The API endpoint allows you to archive a document template. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001" + + req, _ := http.NewRequest("DELETE", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + diff --git a/docs/api/java.md b/docs/api/java.md index 83375022..59b55aad 100644 --- a/docs/api/java.md +++ b/docs/api/java.md @@ -1,253 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```java -HttpResponse response = Unirest.get("https://api.docuseal.com/templates") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```java -HttpResponse response = Unirest.get("https://api.docuseal.com/templates/1000001") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```java -HttpResponse response = Unirest.delete("https://api.docuseal.com/templates/1000001") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```java -HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -363,6 +113,80 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submission } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001/documents") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -526,6 +350,11 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -677,6 +506,15 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -730,6 +568,13 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -754,13 +599,16 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001") +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/pdf") .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") .asString(); ``` @@ -774,20 +622,1460 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submission "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } - ] + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/docx") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/html") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -828,12 +2116,12 @@ HttpResponse response = Unirest.delete("https://api.docuseal.com/submiss } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001/documents") +HttpResponse response = Unirest.get("https://api.docuseal.com/submitters") .header("X-Auth-Token", "API_KEY") .asString(); ``` @@ -846,97 +2134,101 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submission } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/emails") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"template_id\":1000001,\"emails\":\"hi@docuseal.com, example@docuseal.com\"}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1214,6 +2506,15 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/submitters ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1267,6 +2568,13 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/submitters } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1281,12 +2589,12 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/submitters } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submitters") +HttpResponse response = Unirest.get("https://api.docuseal.com/templates") .header("X-Auth-Token", "API_KEY") .asString(); ``` @@ -1299,20 +2607,11 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1320,7 +2619,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1329,30 +2628,8 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1361,7 +2638,25 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1370,7 +2665,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1379,7 +2674,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1388,21 +2683,19 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submitters "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```java -HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001/documents") +HttpResponse response = Unirest.get("https://api.docuseal.com/templates/1000001") .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"documents\":[{\"file\":\"string\"}]}") .asString(); ``` @@ -1416,8 +2709,8 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/templates/ "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", + "summary": "Get a template", + "operationId": "getTemplate", "parameters": [ { "name": "id", @@ -1426,77 +2719,23 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/templates/ "schema": { "type": "integer" }, - "description": "The unique identifier of the documents template.", + "description": "The unique identifier of the document template.", "example": 1000001 } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } + ] } ``` -### Clone a template +### Create a template from PDF + +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 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 -The API endpoint allows you to clone existing template into a new template. ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/1000001/clone") +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/pdf") .header("X-Auth-Token", "API_KEY") .header("content-type", "application/json") - .body("{\"name\":\"Cloned Template\"}") + .body("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") .asString(); ``` @@ -1510,72 +2749,8 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "tags": [ "Templates" ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/html") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\",\"name\":\"Test Template\"}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1584,55 +2759,23 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1640,25 +2783,287 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates }, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1772,7 +3177,8 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1910,6 +3316,15 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1963,6 +3378,13 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1980,16 +3402,15 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/pdf") +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/html") .header("X-Auth-Token", "API_KEY") .header("content-type", "application/json") - .body("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + .body("{\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\",\"name\":\"Test Template\"}") .asString(); ``` @@ -2003,8 +3424,8 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2013,246 +3434,78 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2265,6 +3518,70 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/1000001/clone") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Cloned Template\"}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2348,991 +3665,15 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/pdf") +HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001") .header("X-Auth-Token", "API_KEY") .header("content-type", "application/json") - .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/html") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

Lorem Ipsum is simply dummy text of the\\n\\n\\nand typesetting industry

\\n\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/pdf") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + .body("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") .asString(); ``` @@ -3346,304 +3687,51 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "The name of the template", + "example": "New Document Name" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { + "roles": { "type": "array", + "description": "An array of submitter role names to update the template with.", "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3653,15 +3741,15 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` -### Create a submission from DOCX +### Update template documents -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/docx") +HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001/documents") .header("X-Auth-Token", "API_KEY") .header("content-type", "application/json") - .body("{\"name\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + .body("{\"documents\":[{\"file\":\"string\"}]}") .asString(); ``` @@ -3673,406 +3761,71 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." }, "position": { "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "merge": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -4082,3 +3835,40 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ``` +### Archive a template + +The API endpoint allows you to archive a document template. + +```java +HttpResponse response = Unirest.delete("https://api.docuseal.com/templates/1000001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + diff --git a/docs/api/javascript.md b/docs/api/javascript.md index c0635531..297f4c4c 100644 --- a/docs/api/javascript.md +++ b/docs/api/javascript.md @@ -1,262 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.getTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -await docuseal.archiveTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.updateTemplate(1000001, { - name: "New Document Name", - folder_name: "New Folder" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -374,6 +115,84 @@ const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmissionDocuments(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -546,6 +365,11 @@ const submission = await docuseal.createSubmission({ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -697,6 +521,15 @@ const submission = await docuseal.createSubmission({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -750,6 +583,13 @@ const submission = await docuseal.createSubmission({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -774,16 +614,45 @@ const submission = await docuseal.createSubmission({ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.getSubmission(1001); +const submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); ``` ```json @@ -796,20 +665,1499 @@ const submission = await docuseal.getSubmission(1001); "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromDocx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + name: "string", + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+` + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -852,16 +2200,16 @@ await docuseal.archiveSubmission(1001); } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.getSubmissionDocuments(1001); +const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); ``` ```json @@ -872,100 +2220,101 @@ const submission = await docuseal.getSubmissionDocuments(1001); } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submission = await docuseal.createSubmissionFromEmails({ - template_id: 1000001, - emails: "hi@docuseal.com, example@docuseal.com" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1253,6 +2602,15 @@ const submitter = await docuseal.updateSubmitter(500001, { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1306,6 +2664,13 @@ const submitter = await docuseal.updateSubmitter(500001, { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1320,16 +2685,16 @@ const submitter = await docuseal.updateSubmitter(500001, { } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); ``` ```json @@ -1340,20 +2705,11 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1361,7 +2717,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1370,30 +2726,8 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1402,7 +2736,25 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1411,7 +2763,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1420,7 +2772,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1429,25 +2781,81 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.updateTemplateDocuments(1000001, { +const template = await docuseal.getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromPdf({ + name: "Test PDF", documents: [ { - file: "string" + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ] }); @@ -1463,179 +2871,8 @@ const template = await docuseal.updateTemplateDocuments(1000001, { "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } -} -``` - -### Clone a template - -The API endpoint allows you to clone existing template into a new template. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.cloneTemplate(1000001, { - name: "Cloned Template" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromHtml({ - html: `

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-`, - name: "Test Template" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1644,55 +2881,23 @@ and typesetting industry

"schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1700,25 +2905,287 @@ and typesetting industry

}, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1840,7 +3307,8 @@ const template = await docuseal.createTemplateFromDocx({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1978,6 +3446,15 @@ const template = await docuseal.createTemplateFromDocx({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -2031,6 +3508,13 @@ const template = await docuseal.createTemplateFromDocx({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2048,38 +3532,26 @@ const template = await docuseal.createTemplateFromDocx({ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ] +const template = await docuseal.createTemplateFromHtml({ + html: `

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+`, + name: "Test Template" }); ``` @@ -2093,8 +3565,8 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2103,246 +3575,78 @@ const template = await docuseal.createTemplateFromPdf({ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2355,6 +3659,72 @@ const template = await docuseal.createTemplateFromPdf({ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.cloneTemplate(1000001, { + name: "Cloned Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2444,44 +3814,18 @@ const template = await docuseal.mergeTemplates({ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromPdf({ - name: "Test Submission Document", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] +const template = await docuseal.updateTemplate(1000001, { + name: "New Document Name", + folder_name: "New Folder" }); ``` @@ -2493,507 +3837,53 @@ const submission = await docuseal.createSubmissionFromPdf({ } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3003,502 +3893,19 @@ const submission = await docuseal.createSubmissionFromPdf({ } ``` -### Create a submission from HTML +### Update template documents -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 +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromHtml({ - name: "Test Submission Document", +const template = await docuseal.updateTemplateDocuments(1000001, { documents: [ { - name: "Test Document", - html: `

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-` - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "string" } ] }); @@ -3514,304 +3921,69 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3821,33 +3993,16 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromDocx({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ - { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); +await docuseal.archiveTemplate(1000001); ``` ```json @@ -3858,412 +4013,22 @@ const submission = await docuseal.createSubmissionFromDocx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/api/nodejs.md b/docs/api/nodejs.md index d5865715..c1e00c63 100644 --- a/docs/api/nodejs.md +++ b/docs/api/nodejs.md @@ -1,283 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates", { - method: "GET", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -const { data, pagination } = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/1000001", { - method: "GET", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/1000001", { - method: "DELETE", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/1000001", { - method: "PUT", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "New Document Name", - folder_name: "New Folder" - }) -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -400,6 +120,94 @@ const { data, pagination } = await resp.json(); } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/1001", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const submission = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/1001/documents", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const submission = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -578,6 +386,11 @@ const submitters = await resp.json(); "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -729,6 +542,15 @@ const submitters = await resp.json(); ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -782,6 +604,13 @@ const submitters = await resp.json(); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -806,18 +635,48 @@ const submitters = await resp.json(); } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submissions/1001", { - method: "GET", +const resp = await fetch("https://api.docuseal.com/submissions/pdf", { + method: "POST", headers: { "X-Auth-Token": "API_KEY" - } + }, + body: JSON.stringify({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] + }) }); const submission = await resp.json(); @@ -833,20 +692,1511 @@ const submission = await resp.json(); "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } - ] + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/docx", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ + { + name: "string", + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] + }) +}); + +const submitters = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/html", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+` + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] + }) +}); + +const submission = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -894,21 +2244,21 @@ await resp.json(); } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submissions/1001/documents", { +const resp = await fetch("https://api.docuseal.com/submitters", { method: "GET", headers: { "X-Auth-Token": "API_KEY" } }); -const submission = await resp.json(); +const { data, pagination } = await resp.json(); ``` ```json @@ -919,106 +2269,101 @@ const submission = await resp.json(); } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions/emails", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - template_id: 1000001, - emails: "hi@docuseal.com, example@docuseal.com" - }) -}); - -const submitters = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1317,6 +2662,15 @@ const submitter = await resp.json(); ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1370,6 +2724,13 @@ const submitter = await resp.json(); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1384,14 +2745,14 @@ const submitter = await resp.json(); } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submitters", { +const resp = await fetch("https://api.docuseal.com/templates", { method: "GET", headers: { "X-Auth-Token": "API_KEY" @@ -1409,20 +2770,11 @@ const { data, pagination } = await resp.json(); } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1430,7 +2782,7 @@ const { data, pagination } = await resp.json(); "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1439,30 +2791,8 @@ const { data, pagination } = await resp.json(); "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1471,7 +2801,25 @@ const { data, pagination } = await resp.json(); "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1480,7 +2828,7 @@ const { data, pagination } = await resp.json(); "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1489,7 +2837,7 @@ const { data, pagination } = await resp.json(); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1498,28 +2846,89 @@ const { data, pagination } = await resp.json(); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates/1000001/documents", { - method: "PUT", +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/pdf", { + method: "POST", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ + name: "Test PDF", documents: [ { - file: "string" + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ] }) @@ -1538,69 +2947,321 @@ const template = await resp.json(); "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "documents" + ], "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", - "description": "The list of documents to add or replace in the template.", "items": { "type": "object", + "required": [ + "name", + "file" + ], "properties": { "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Name of the document." }, "file": { + "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } }, - "merge": { + "flatten": { "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1610,20 +3271,27 @@ const template = await resp.json(); } ``` -### Clone a template +### Create a template from Word DOCX + +The API endpoint provides the functionality to create a fillable document template for 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 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 -The API endpoint allows you to clone existing template into a new template. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates/1000001/clone", { +const resp = await fetch("https://api.docuseal.com/templates/docx", { method: "POST", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "Cloned Template" + name: "Test DOCX", + documents: [ + { + name: "string", + file: "base64" + } + ] }) }); @@ -1640,39 +3308,303 @@ const template = await resp.json(); "tags": [ "Templates" ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "documents" + ], "properties": { "name": { "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." + "description": "Name of the template", + "example": "Test DOCX" }, "external_id": { "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new document.", + "example": "unique-key" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } } } } @@ -1815,27 +3747,20 @@ const template = await resp.json(); } ``` -### Create a template from Word DOCX - -The API endpoint provides the functionality to create a fillable document template for 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 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 +### Clone a template +The API endpoint allows you to clone existing template into a new template. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates/docx", { +const resp = await fetch("https://api.docuseal.com/templates/1000001/clone", { method: "POST", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "Test DOCX", - documents: [ - { - name: "string", - file: "base64" - } - ] + name: "Cloned Template" }) }); @@ -1852,599 +3777,39 @@ const template = await resp.json(); "tags": [ "Templates" ], - "summary": "Create a template from Word DOCX", - "operationId": "createTemplateFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test DOCX" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new document.", - "example": "unique-key" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" - }, - "fields": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1." - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 - - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/pdf", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ] - }) -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ { - "AuthToken": [] + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 } ], - "tags": [ - "Templates" - ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be cloned." }, "external_id": { "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } + "description": "Your application-specific unique string key to identify this template within your app." } } } @@ -2549,51 +3914,25 @@ const template = await resp.json(); } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submissions/pdf", { - method: "POST", +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "PUT", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "Test Submission Document", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] + name: "New Document Name", + folder_name: "New Folder" }) }); -const submission = await resp.json(); +const template = await resp.json(); ``` ```json @@ -2604,979 +3943,53 @@ const submission = await resp.json(); } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions/html", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Test Submission Document", - documents: [ - { - name: "Test Document", - html: `

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-` - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] - }) -}); - -const submission = await resp.json(); -``` - -```json -{ - "security": [ + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ { - "AuthToken": [] + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "archived": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false + "description": "Set `false` to unarchive template." } } } @@ -3586,39 +3999,22 @@ const submission = await resp.json(); } ``` -### Create a template from PDF - -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 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 +### Update template documents +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates/pdf", { - method: "POST", +const resp = await fetch("https://api.docuseal.com/templates/1000001/documents", { + method: "PUT", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "Test PDF", documents: [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "string" } ] }) @@ -3637,304 +4033,69 @@ const template = await resp.json(); "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3944,39 +4105,21 @@ const template = await resp.json(); } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submissions/docx", { - method: "POST", +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "DELETE", headers: { "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ - { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] - }) + } }); -const submitters = await resp.json(); +await resp.json(); ``` ```json @@ -3987,412 +4130,22 @@ const submitters = await resp.json(); } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/api/php.md b/docs/api/php.md index 81c10af2..a56fe2ca 100644 --- a/docs/api/php.md +++ b/docs/api/php.md @@ -1,254 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->listTemplates(['limit' => 10]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->getTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->archiveTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->updateTemplate(1000001, [ - 'name' => 'New Document Name', - 'folder_name' => 'New Folder' -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -364,6 +113,80 @@ $docuseal->listSubmissions(['limit' => 10]); } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->getSubmissionDocuments(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -534,6 +357,11 @@ $docuseal->createSubmission([ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -685,6 +513,15 @@ $docuseal->createSubmission([ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -738,6 +575,13 @@ $docuseal->createSubmission([ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -762,14 +606,43 @@ $docuseal->createSubmission([ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->getSubmission(1001); +$docuseal->createSubmissionFromPdf([ + 'name' => 'Test Submission Document', + 'documents' => [ + [ + 'name' => 'string', + 'file' => 'base64', + 'fields' => [ + [ + 'name' => 'string', + 'areas' => [ + [ + 'x' => 0, + 'y' => 0, + 'w' => 0, + 'h' => 0, + 'page' => 1 + ] + ] + ] + ] + ] + ], + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] + ] +]); ``` ```json @@ -782,20 +655,1495 @@ $docuseal->getSubmission(1001); "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->createSubmissionFromDocx([ + 'name' => 'Test Submission Document', + 'variables' => [ + 'variable_name' => 'value' + ], + 'documents' => [ + [ + 'name' => 'string', + 'file' => 'base64' + ] + ], + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] ] +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->createSubmissionFromHtml([ + 'name' => 'Test Submission Document', + 'documents' => [ + [ + 'name' => 'Test Document', + 'html' => '

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+' + ] + ], + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] + ] +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -836,14 +2184,14 @@ $docuseal->archiveSubmission(1001); } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->getSubmissionDocuments(1001); +$docuseal->listSubmitters(['limit' => 10]); ``` ```json @@ -854,98 +2202,101 @@ $docuseal->getSubmissionDocuments(1001); } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->createSubmissionFromEmails([ - 'template_id' => 1000001, - 'emails' => 'hi@docuseal.com, example@docuseal.com' -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1229,6 +2580,15 @@ $docuseal->updateSubmitter(500001, [ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1282,6 +2642,13 @@ $docuseal->updateSubmitter(500001, [ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1296,14 +2663,14 @@ $docuseal->updateSubmitter(500001, [ } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->listSubmitters(['limit' => 10]); +$docuseal->listTemplates(['limit' => 10]); ``` ```json @@ -1314,20 +2681,11 @@ $docuseal->listSubmitters(['limit' => 10]); } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1335,7 +2693,7 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1344,30 +2702,8 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1376,7 +2712,25 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1385,7 +2739,7 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1394,7 +2748,7 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1403,23 +2757,77 @@ $docuseal->listSubmitters(['limit' => 10]); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->updateTemplateDocuments(1000001, [ +$docuseal->getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->createTemplateFromPdf([ + 'name' => 'Test PDF', 'documents' => [ [ - 'file' => 'string' + 'name' => 'string', + 'file' => 'base64', + 'fields' => [ + [ + 'name' => 'string', + 'areas' => [ + [ + 'x' => 0, + 'y' => 0, + 'w' => 0, + 'h' => 0, + 'page' => 1 + ] + ] + ] + ] ] ] ]); @@ -1435,175 +2843,8 @@ $docuseal->updateTemplateDocuments(1000001, [ "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } -} -``` - -### Clone a template - -The API endpoint allows you to clone existing template into a new template. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->cloneTemplate(1000001, [ - 'name' => 'Cloned Template' -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->createTemplateFromHtml([ - 'html' => '

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-', - 'name' => 'Test Template' -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1612,55 +2853,23 @@ and typesetting industry

"schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1668,25 +2877,287 @@ and typesetting industry

}, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1806,7 +3277,8 @@ $docuseal->createTemplateFromDocx([ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1944,6 +3416,15 @@ $docuseal->createTemplateFromDocx([ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1997,6 +3478,13 @@ $docuseal->createTemplateFromDocx([ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2014,36 +3502,24 @@ $docuseal->createTemplateFromDocx([ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->createTemplateFromPdf([ - 'name' => 'Test PDF', - 'documents' => [ - [ - 'name' => 'string', - 'file' => 'base64', - 'fields' => [ - [ - 'name' => 'string', - 'areas' => [ - [ - 'x' => 0, - 'y' => 0, - 'w' => 0, - 'h' => 0, - 'page' => 1 - ] - ] - ] - ] - ] - ] +$docuseal->createTemplateFromHtml([ + 'html' => '

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+', + 'name' => 'Test Template' ]); ``` @@ -2057,8 +3533,8 @@ $docuseal->createTemplateFromPdf([ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2067,246 +3543,78 @@ $docuseal->createTemplateFromPdf([ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2319,6 +3627,70 @@ $docuseal->createTemplateFromPdf([ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->cloneTemplate(1000001, [ + 'name' => 'Cloned Template' +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2406,42 +3778,16 @@ $docuseal->mergeTemplates([ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->createSubmissionFromPdf([ - 'name' => 'Test Submission Document', - 'documents' => [ - [ - 'name' => 'string', - 'file' => 'base64', - 'fields' => [ - [ - 'name' => 'string', - 'areas' => [ - [ - 'x' => 0, - 'y' => 0, - 'w' => 0, - 'h' => 0, - 'page' => 1 - ] - ] - ] - ] - ] - ], - 'submitters' => [ - [ - 'role' => 'First Party', - 'email' => 'john.doe@example.com' - ] - ] +$docuseal->updateTemplate(1000001, [ + 'name' => 'New Document Name', + 'folder_name' => 'New Folder' ]); ``` @@ -2453,971 +3799,53 @@ $docuseal->createSubmissionFromPdf([ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->createSubmissionFromHtml([ - 'name' => 'Test Submission Document', - 'documents' => [ - [ - 'name' => 'Test Document', - 'html' => '

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-' - ] - ], - 'submitters' => [ - [ - 'role' => 'First Party', - 'email' => 'john.doe@example.com' - ] - ] -]); -``` - -```json -{ - "security": [ + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ { - "AuthToken": [] + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "archived": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false + "description": "Set `false` to unarchive template." } } } @@ -3427,34 +3855,17 @@ and typesetting industry

} ``` -### Create a template from PDF - -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 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 +### Update template documents +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->createTemplateFromPdf([ - 'name' => 'Test PDF', +$docuseal->updateTemplateDocuments(1000001, [ 'documents' => [ [ - 'name' => 'string', - 'file' => 'base64', - 'fields' => [ - [ - 'name' => 'string', - 'areas' => [ - [ - 'x' => 0, - 'y' => 0, - 'w' => 0, - 'h' => 0, - 'page' => 1 - ] - ] - ] - ] + 'file' => 'string' ] ] ]); @@ -3470,304 +3881,69 @@ $docuseal->createTemplateFromPdf([ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3777,31 +3953,14 @@ $docuseal->createTemplateFromPdf([ } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->createSubmissionFromDocx([ - 'name' => 'Test Submission Document', - 'variables' => [ - 'variable_name' => 'value' - ], - 'documents' => [ - [ - 'name' => 'string', - 'file' => 'base64' - ] - ], - 'submitters' => [ - [ - 'role' => 'First Party', - 'email' => 'john.doe@example.com' - ] - ] -]); +$docuseal->archiveTemplate(1000001); ``` ```json @@ -3812,412 +3971,22 @@ $docuseal->createSubmissionFromDocx([ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/api/python.md b/docs/api/python.md index 07dc3bbd..28940996 100644 --- a/docs/api/python.md +++ b/docs/api/python.md @@ -1,266 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.list_submissions({ "limit": 10 }) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.get_template(1000001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.archive_template(1000001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.update_template(1000001, { - "name": "New Document Name", - "folder_name": "New Folder" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -379,6 +116,86 @@ docuseal.list_submissions({ "limit": 10 }) } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.get_submission(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.get_submission_documents(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -552,6 +369,11 @@ docuseal.create_submission({ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -703,6 +525,15 @@ docuseal.create_submission({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -756,6 +587,13 @@ docuseal.create_submission({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -780,9 +618,10 @@ docuseal.create_submission({ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```python from docuseal import docuseal @@ -790,7 +629,35 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.get_submission(1001) +docuseal.create_submission_from_pdf({ + "name": "Test Submission Document", + "documents": [ + { + "name": "string", + "file": "base64", + "fields": [ + { + "name": "string", + "areas": [ + { + "x": 0, + "y": 0, + "w": 0, + "h": 0, + "page": 1 + } + ] + } + ] + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" + } + ] +}) ``` ```json @@ -803,20 +670,1501 @@ docuseal.get_submission(1001) "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.create_submission_from_docx({ + "name": "Test Submission Document", + "variables": { + "variable_name": "value" + }, + "documents": [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "name": "string", + "file": "base64" + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" } ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.create_submission_from_html({ + "name": "Test Submission Document", + "documents": [ + { + "name": "Test Document", + "html": """

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+""" + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -860,9 +2208,9 @@ docuseal.archive_submission(1001) } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```python from docuseal import docuseal @@ -870,7 +2218,7 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.get_submission_documents(1001) +docuseal.list_submissions({ "limit": 10 }) ``` ```json @@ -881,101 +2229,101 @@ docuseal.get_submission_documents(1001) } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.create_submission_from_emails({ - "template_id": 1000001, - "emails": "hi@docuseal.com, example@docuseal.com" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1265,6 +2613,15 @@ docuseal.update_submitter(500001, { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1318,6 +2675,13 @@ docuseal.update_submitter(500001, { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1332,9 +2696,9 @@ docuseal.update_submitter(500001, { } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```python from docuseal import docuseal @@ -1353,20 +2717,11 @@ docuseal.list_submissions({ "limit": 10 }) } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1374,7 +2729,7 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1383,30 +2738,8 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1415,7 +2748,25 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1424,7 +2775,7 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1433,7 +2784,7 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1442,15 +2793,15 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```python from docuseal import docuseal @@ -1458,10 +2809,67 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.update_template_documents(1000001, { +docuseal.get_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.create_template_from_pdf({ + "name": "Test PDF", "documents": [ { - "file": "string" + "name": "string", + "file": "base64", + "fields": [ + { + "name": "string", + "areas": [ + { + "x": 0, + "y": 0, + "w": 0, + "h": 0, + "page": 1 + } + ] + } + ] } ] }) @@ -1477,181 +2885,8 @@ docuseal.update_template_documents(1000001, { "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } -} -``` - -### Clone a template - -The API endpoint allows you to clone existing template into a new template. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.clone_template(1000001, { - "name": "Cloned Template" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.create_template_from_html({ - "html": """

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-""", - "name": "Test Template" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1660,55 +2895,23 @@ and typesetting industry

"schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1716,25 +2919,287 @@ and typesetting industry

}, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1857,7 +3322,8 @@ docuseal.create_template_from_docx({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1995,6 +3461,15 @@ docuseal.create_template_from_docx({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -2048,6 +3523,13 @@ docuseal.create_template_from_docx({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2065,10 +3547,9 @@ docuseal.create_template_from_docx({ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```python from docuseal import docuseal @@ -2076,28 +3557,17 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_template_from_pdf({ - "name": "Test PDF", - "documents": [ - { - "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] - } - ] +docuseal.create_template_from_html({ + "html": """

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+""", + "name": "Test Template" }) ``` @@ -2111,8 +3581,8 @@ docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2121,246 +3591,78 @@ docuseal.create_template_from_pdf({ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2373,6 +3675,73 @@ docuseal.create_template_from_pdf({ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.clone_template(1000001, { + "name": "Cloned Template" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2463,10 +3832,9 @@ docuseal.merge_templates({ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```python from docuseal import docuseal @@ -2474,34 +3842,9 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_submission_from_pdf({ - "name": "Test Submission Document", - "documents": [ - { - "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] - } - ], - "submitters": [ - { - "role": "First Party", - "email": "john.doe@example.com" - } - ] +docuseal.update_template(1000001, { + "name": "New Document Name", + "folder_name": "New Folder" }) ``` @@ -2513,507 +3856,53 @@ docuseal.create_submission_from_pdf({ } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3023,9 +3912,9 @@ docuseal.create_submission_from_pdf({ } ``` -### Create a submission from HTML +### Update template documents -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 +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```python from docuseal import docuseal @@ -3033,494 +3922,10 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_submission_from_html({ - "name": "Test Submission Document", +docuseal.update_template_documents(1000001, { "documents": [ { - "name": "Test Document", - "html": """

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-""" - } - ], - "submitters": [ - { - "role": "First Party", - "email": "john.doe@example.com" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.create_template_from_pdf({ - "name": "Test PDF", - "documents": [ - { - "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] + "file": "string" } ] }) @@ -3536,304 +3941,69 @@ docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3843,9 +4013,9 @@ docuseal.create_template_from_pdf({ } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```python from docuseal import docuseal @@ -3853,24 +4023,7 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_submission_from_docx({ - "name": "Test Submission Document", - "variables": { - "variable_name": "value" - }, - "documents": [ - { - "name": "string", - "file": "base64" - } - ], - "submitters": [ - { - "role": "First Party", - "email": "john.doe@example.com" - } - ] -}) +docuseal.archive_template(1000001) ``` ```json @@ -3881,412 +4034,22 @@ docuseal.create_submission_from_docx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/api/ruby.md b/docs/api/ruby.md index 45be27ae..cb5a84aa 100644 --- a/docs/api/ruby.md +++ b/docs/api/ruby.md @@ -1,266 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.list_templates(limit: 10) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.get_template(1000001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.archive_template(1000001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.update_template(1000001, { - name: "New Document Name", - folder_name: "New Folder" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -379,6 +116,86 @@ Docuseal.list_submissions(limit: 10) } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.get_submission(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.get_submission_documents(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -552,6 +369,11 @@ Docuseal.create_submission({ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -703,6 +525,15 @@ Docuseal.create_submission({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -756,6 +587,13 @@ Docuseal.create_submission({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -780,9 +618,10 @@ Docuseal.create_submission({ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```ruby require "docuseal" @@ -790,7 +629,35 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.get_submission(1001) +Docuseal.create_submission_from_pdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}) ``` ```json @@ -803,20 +670,1501 @@ Docuseal.get_submission(1001) "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.create_submission_from_docx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + name: "string", + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.create_submission_from_html({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: "

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -860,9 +2208,9 @@ Docuseal.archive_submission(1001) } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```ruby require "docuseal" @@ -870,7 +2218,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.get_submission_documents(1001) +Docuseal.list_submitters(limit: 10) ``` ```json @@ -881,101 +2229,101 @@ Docuseal.get_submission_documents(1001) } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.create_submission_from_emails({ - template_id: 1000001, - emails: "hi@docuseal.com, example@docuseal.com" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1265,6 +2613,15 @@ Docuseal.update_submitter(500001, { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1318,6 +2675,13 @@ Docuseal.update_submitter(500001, { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1332,9 +2696,9 @@ Docuseal.update_submitter(500001, { } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```ruby require "docuseal" @@ -1342,7 +2706,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.list_submitters(limit: 10) +Docuseal.list_templates(limit: 10) ``` ```json @@ -1353,20 +2717,11 @@ Docuseal.list_submitters(limit: 10) } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1374,7 +2729,7 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1383,30 +2738,8 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1415,7 +2748,25 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1424,7 +2775,7 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1433,7 +2784,7 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1442,15 +2793,15 @@ Docuseal.list_submitters(limit: 10) "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```ruby require "docuseal" @@ -1458,10 +2809,67 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.update_template_documents(1000001, { +Docuseal.get_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.create_template_from_pdf({ + name: "Test PDF", documents: [ { - file: "string" + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ] }) @@ -1477,181 +2885,8 @@ Docuseal.update_template_documents(1000001, { "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } -} -``` - -### Clone a template - -The API endpoint allows you to clone existing template into a new template. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.clone_template(1000001, { - name: "Cloned Template" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.create_template_from_html({ - html: "

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-", - name: "Test Template" -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1660,55 +2895,23 @@ and typesetting industry

"schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1716,25 +2919,287 @@ and typesetting industry

}, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1857,7 +3322,8 @@ Docuseal.create_template_from_docx({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1995,6 +3461,15 @@ Docuseal.create_template_from_docx({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -2048,6 +3523,13 @@ Docuseal.create_template_from_docx({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2065,10 +3547,9 @@ Docuseal.create_template_from_docx({ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```ruby require "docuseal" @@ -2076,28 +3557,17 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_template_from_pdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ] +Docuseal.create_template_from_html({ + html: "

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+", + name: "Test Template" }) ``` @@ -2111,8 +3581,8 @@ Docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2121,246 +3591,78 @@ Docuseal.create_template_from_pdf({ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2373,6 +3675,73 @@ Docuseal.create_template_from_pdf({ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.clone_template(1000001, { + name: "Cloned Template" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2463,10 +3832,9 @@ Docuseal.merge_templates({ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```ruby require "docuseal" @@ -2474,34 +3842,9 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_submission_from_pdf({ - name: "Test Submission Document", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] +Docuseal.update_template(1000001, { + name: "New Document Name", + folder_name: "New Folder" }) ``` @@ -2513,507 +3856,53 @@ Docuseal.create_submission_from_pdf({ } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3023,9 +3912,9 @@ Docuseal.create_submission_from_pdf({ } ``` -### Create a submission from HTML +### Update template documents -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 +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```ruby require "docuseal" @@ -3033,494 +3922,10 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_submission_from_html({ - name: "Test Submission Document", +Docuseal.update_template_documents(1000001, { documents: [ { - name: "Test Document", - html: "

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.create_template_from_pdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "string" } ] }) @@ -3536,304 +3941,69 @@ Docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3843,9 +4013,9 @@ Docuseal.create_template_from_pdf({ } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```ruby require "docuseal" @@ -3853,24 +4023,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_submission_from_docx({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ - { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}) +Docuseal.archive_template(1000001) ``` ```json @@ -3881,412 +4034,22 @@ Docuseal.create_submission_from_docx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/api/shell.md b/docs/api/shell.md index f5132490..1e0b6cf1 100644 --- a/docs/api/shell.md +++ b/docs/api/shell.md @@ -1,253 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```shell -curl --request GET \ - --url https://api.docuseal.com/templates \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```shell -curl --request GET \ - --url https://api.docuseal.com/templates/1000001 \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```shell -curl --request DELETE \ - --url https://api.docuseal.com/templates/1000001 \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```shell -curl --request PUT \ - --url https://api.docuseal.com/templates/1000001 \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"name":"New Document Name","folder_name":"New Folder"}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -363,6 +113,80 @@ curl --request GET \ } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```shell +curl --request GET \ + --url https://api.docuseal.com/submissions/1001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```shell +curl --request GET \ + --url https://api.docuseal.com/submissions/1001/documents \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -526,6 +350,11 @@ curl --request POST \ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -677,6 +506,15 @@ curl --request POST \ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -730,6 +568,13 @@ curl --request POST \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -754,14 +599,17 @@ curl --request POST \ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```shell -curl --request GET \ - --url https://api.docuseal.com/submissions/1001 \ - --header 'X-Auth-Token: API_KEY' +curl --request POST \ + --url https://api.docuseal.com/submissions/pdf \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test Submission Document","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' ``` ```json @@ -774,20 +622,1460 @@ curl --request GET \ "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } } - ] + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```shell +curl --request POST \ + --url https://api.docuseal.com/submissions/docx \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test Submission Document","variables":{"variable_name":"value"},"documents":[{"name":"string","file":"base64"}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```shell +curl --request POST \ + --url https://api.docuseal.com/submissions/html \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test Submission Document","documents":[{"name":"Test Document","html":"

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n"}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -828,13 +2116,13 @@ curl --request DELETE \ } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```shell curl --request GET \ - --url https://api.docuseal.com/submissions/1001/documents \ + --url https://api.docuseal.com/submitters \ --header 'X-Auth-Token: API_KEY' ``` @@ -846,97 +2134,101 @@ curl --request GET \ } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```shell -curl --request POST \ - --url https://api.docuseal.com/submissions/emails \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"template_id":1000001,"emails":"hi@docuseal.com, example@docuseal.com"}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1214,6 +2506,15 @@ curl --request PUT \ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1267,6 +2568,13 @@ curl --request PUT \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1281,13 +2589,13 @@ curl --request PUT \ } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```shell curl --request GET \ - --url https://api.docuseal.com/submitters \ + --url https://api.docuseal.com/templates \ --header 'X-Auth-Token: API_KEY' ``` @@ -1299,20 +2607,11 @@ curl --request GET \ } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1320,7 +2619,7 @@ curl --request GET \ "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1329,30 +2628,8 @@ curl --request GET \ "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1361,7 +2638,25 @@ curl --request GET \ "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1370,7 +2665,7 @@ curl --request GET \ "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1379,7 +2674,7 @@ curl --request GET \ "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1388,22 +2683,20 @@ curl --request GET \ "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```shell -curl --request PUT \ - --url https://api.docuseal.com/templates/1000001/documents \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"documents":[{"file":"string"}]}' +curl --request GET \ + --url https://api.docuseal.com/templates/1000001 \ + --header 'X-Auth-Token: API_KEY' ``` ```json @@ -1416,8 +2709,8 @@ curl --request PUT \ "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", + "summary": "Get a template", + "operationId": "getTemplate", "parameters": [ { "name": "id", @@ -1426,78 +2719,24 @@ curl --request PUT \ "schema": { "type": "integer" }, - "description": "The unique identifier of the documents template.", + "description": "The unique identifier of the document template.", "example": 1000001 } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } + ] } ``` -### Clone a template +### Create a template from PDF + +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 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 -The API endpoint allows you to clone existing template into a new template. ```shell curl --request POST \ - --url https://api.docuseal.com/templates/1000001/clone \ + --url https://api.docuseal.com/templates/pdf \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ - --data '{"name":"Cloned Template"}' + --data '{"name":"Test PDF","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}]}' ``` ```json @@ -1510,72 +2749,8 @@ curl --request POST \ "tags": [ "Templates" ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```shell -curl --request POST \ - --url https://api.docuseal.com/templates/html \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"html":"

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n","name":"Test Template"}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1584,55 +2759,23 @@ curl --request POST \ "schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1640,25 +2783,287 @@ curl --request POST \ }, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1772,7 +3177,8 @@ curl --request POST \ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1910,6 +3316,15 @@ curl --request POST \ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1963,6 +3378,13 @@ curl --request POST \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1980,17 +3402,16 @@ curl --request POST \ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```shell curl --request POST \ - --url https://api.docuseal.com/templates/pdf \ + --url https://api.docuseal.com/templates/html \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ - --data '{"name":"Test PDF","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}]}' + --data '{"html":"

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n","name":"Test Template"}' ``` ```json @@ -2003,8 +3424,8 @@ curl --request POST \ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2013,246 +3434,78 @@ curl --request POST \ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2265,6 +3518,70 @@ curl --request POST \ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```shell +curl --request POST \ + --url https://api.docuseal.com/templates/1000001/clone \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Cloned Template"}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2348,992 +3665,16 @@ curl --request POST \ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```shell -curl --request POST \ - --url https://api.docuseal.com/submissions/pdf \ +curl --request PUT \ + --url https://api.docuseal.com/templates/1000001 \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ - --data '{"name":"Test Submission Document","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } - } - } -} -``` - -### Create a submission from HTML - -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 - -```shell -curl --request POST \ - --url https://api.docuseal.com/submissions/html \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"name":"Test Submission Document","documents":[{"name":"Test Document","html":"

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n"}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```shell -curl --request POST \ - --url https://api.docuseal.com/templates/pdf \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"name":"Test PDF","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}]}' + --data '{"name":"New Document Name","folder_name":"New Folder"}' ``` ```json @@ -3346,304 +3687,51 @@ curl --request POST \ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "The name of the template", + "example": "New Document Name" }, "folder_name": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, - "documents": { + "roles": { "type": "array", + "description": "An array of submitter role names to update the template with.", "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - } - } - } + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3653,16 +3741,16 @@ curl --request POST \ } ``` -### Create a submission from DOCX +### Update template documents -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```shell -curl --request POST \ - --url https://api.docuseal.com/submissions/docx \ +curl --request PUT \ + --url https://api.docuseal.com/templates/1000001/documents \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ - --data '{"name":"Test Submission Document","variables":{"variable_name":"value"},"documents":[{"name":"string","file":"base64"}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' + --data '{"documents":[{"file":"string"}]}' ``` ```json @@ -3673,406 +3761,71 @@ curl --request POST \ } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." }, "position": { "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { + "merge": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -4082,3 +3835,40 @@ curl --request POST \ } ``` +### Archive a template + +The API endpoint allows you to archive a document template. + +```shell +curl --request DELETE \ + --url https://api.docuseal.com/templates/1000001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + diff --git a/docs/api/typescript.md b/docs/api/typescript.md index 65d4b084..997ed02d 100644 --- a/docs/api/typescript.md +++ b/docs/api/typescript.md @@ -1,262 +1,3 @@ -### List all templates - -The API endpoint provides the ability to retrieve a list of available document templates. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "List all templates", - "operationId": "getTemplates", - "parameters": [ - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates based on the name partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" - }, - { - "name": "external_id", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." - }, - { - "name": "folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter templates by folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Get only archived templates instead of active ones." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." - }, - { - "name": "after", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." - } - ] -} -``` - -### Get a template - -The API endpoint provides the functionality to retrieve information about a document template. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.getTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Get a template", - "operationId": "getTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Archive a template - -The API endpoint allows you to archive a document template. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -await docuseal.archiveTemplate(1000001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Archive a template", - "operationId": "archiveTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ] -} -``` - -### Update a template - -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.updateTemplate(1000001, { - name: "New Document Name", - folder_name: "New Folder" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Update a template", - "operationId": "updateTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the document template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the template", - "example": "New Document Name" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to update the template with.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - }, - "archived": { - "type": "boolean", - "description": "Set `false` to unarchive template." - } - } - } - } - } - } -} -``` - ### List all submissions The API endpoint provides the ability to retrieve a list of available submissions. @@ -374,6 +115,84 @@ const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); } ``` +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmissionDocuments(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + ### Create a submission 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
Pre-fill PDF document form fields with API @@ -546,6 +365,11 @@ const submission = await docuseal.createSubmission({ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -697,6 +521,15 @@ const submission = await docuseal.createSubmission({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -750,6 +583,13 @@ const submission = await docuseal.createSubmission({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -774,16 +614,45 @@ const submission = await docuseal.createSubmission({ } ``` -### Get a submission +### Create a submission from PDF + +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 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 -The API endpoint provides the functionality to retrieve information about a submission. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.getSubmission(1001); +const submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); ``` ```json @@ -796,20 +665,1499 @@ const submission = await docuseal.getSubmission(1001); "tags": [ "Submissions" ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from DOCX + +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 for the specific text variable syntax, including dynamic content tables and list. 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 + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromDocx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + name: "string", + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "variables": { + "type": "object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", + "example": { + "variable_name": "value" + } + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +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 + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+` + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "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", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "order": { + "type": "integer", + "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } } ``` @@ -852,16 +2200,16 @@ await docuseal.archiveSubmission(1001); } ``` -### Get submission documents +### List all submitters -This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. +The API endpoint provides the ability to retrieve a list of submitters. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.getSubmissionDocuments(1001); +const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); ``` ```json @@ -872,100 +2220,101 @@ const submission = await docuseal.getSubmissionDocuments(1001); } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Get submission documents", - "operationId": "getSubmissionDocuments", + "summary": "List all submitters", + "operationId": "getSubmitters", "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "submission_id", + "in": "query", + "required": false, "schema": { "type": "integer" }, - "description": "The unique identifier of the submission.", - "example": 1001 + "description": "The submission ID allows you to receive only the submitters related to that specific submission." + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters on name, email or phone partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter submitters by unique slug.", + "example": "zAyL9fH36Havvm" + }, + { + "name": "completed_after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-05 9:32:20", + "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." + }, + { + "name": "completed_before", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-03-06 19:32:20", + "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ] } ``` -### Create submissions from emails - -This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submission = await docuseal.createSubmissionFromEmails({ - template_id: 1000001, - emails: "hi@docuseal.com, example@docuseal.com" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create submissions from emails", - "operationId": "createSubmissionsFromEmails", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "emails" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { - "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." - } - } - } - } - } - } - } - } -} -``` - ### Get a submitter The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. @@ -1253,6 +2602,15 @@ const submitter = await docuseal.updateSubmitter(500001, { ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1306,6 +2664,13 @@ const submitter = await docuseal.updateSubmitter(500001, { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -1320,16 +2685,16 @@ const submitter = await docuseal.updateSubmitter(500001, { } ``` -### List all submitters +### List all templates -The API endpoint provides the ability to retrieve a list of submitters. +The API endpoint provides the ability to retrieve a list of available document templates. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); ``` ```json @@ -1340,20 +2705,11 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); } ], "tags": [ - "Submitters" + "Templates" ], - "summary": "List all submitters", - "operationId": "getSubmitters", + "summary": "List all templates", + "operationId": "getTemplates", "parameters": [ - { - "name": "submission_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The submission ID allows you to receive only the submitters related to that specific submission." - }, { "name": "q", "in": "query", @@ -1361,7 +2717,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "Filter submitters on name, email or phone partial match." + "description": "Filter templates based on the name partial match." }, { "name": "slug", @@ -1370,30 +2726,8 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "Filter submitters by unique slug.", - "example": "zAyL9fH36Havvm" - }, - { - "name": "completed_after", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-05 9:32:20", - "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." - }, - { - "name": "completed_before", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2024-03-06 19:32:20", - "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" }, { "name": "external_id", @@ -1402,7 +2736,25 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "string" }, - "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." }, { "name": "limit", @@ -1411,7 +2763,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The number of submitters to return. Default value is 10. Maximum value is 100." + "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -1420,7 +2772,7 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", @@ -1429,25 +2781,81 @@ const { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ] } ``` -### Update template documents +### Get a template -The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. +The API endpoint provides the functionality to retrieve information about a document template. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.updateTemplateDocuments(1000001, { +const template = await docuseal.getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Create a template from PDF + +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 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 + + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromPdf({ + name: "Test PDF", documents: [ { - file: "string" + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ] }); @@ -1463,179 +2871,8 @@ const template = await docuseal.updateTemplateDocuments(1000001, { "tags": [ "Templates" ], - "summary": "Update template documents", - "operationId": "addDocumentToTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "description": "The list of documents to add or replace in the template.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "file": { - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." - }, - "html": { - "type": "string", - "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." - }, - "position": { - "type": "integer", - "description": "Position of the document. By default will be added as the last document in the template.", - "example": 0 - }, - "replace": { - "type": "boolean", - "default": false, - "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." - }, - "remove": { - "type": "boolean", - "default": false, - "description": "Set to `true` to remove existing document at given `position` or with given `name`." - } - } - } - }, - "merge": { - "type": "boolean", - "default": false, - "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." - } - } - } - } - } - } -} -``` - -### Clone a template - -The API endpoint allows you to clone existing template into a new template. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.cloneTemplate(1000001, { - name: "Cloned Template" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Clone a template", - "operationId": "cloneTemplate", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the documents template.", - "example": 1000001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - } - } - } - } - } - } -} -``` - -### 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.
Related Guides
Create PDF document fillable form with HTML - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromHtml({ - html: `

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-`, - name: "Test Template" -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1644,55 +2881,23 @@ and typesetting industry

"schema": { "type": "object", "required": [ - "html" + "documents" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML template of the footer to be displayed on every page." - }, "name": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", - "example": "714d974e-83d8-11ee-b962-0242ac120002" + "description": "Name of the template", + "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, "shared_link": { "type": "boolean", "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", @@ -1700,25 +2905,287 @@ and typesetting industry

}, "documents": { "type": "array", - "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "properties": { - "html": { - "type": "string", - "description": "HTML template with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification", + "strikethrough" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "validation": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" + }, + "message": { + "type": "string", + "description": "A custom error message to display on validation failure." + }, + "min": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Minimum allowed number value or date depending on field type." + }, + "max": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "description": "Maximum allowed number value or date depending on field type." + }, + "step": { + "type": "number", + "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -1840,7 +3307,8 @@ const template = await docuseal.createTemplateFromDocx({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1978,6 +3446,15 @@ const template = await docuseal.createTemplateFromDocx({ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -2031,6 +3508,13 @@ const template = await docuseal.createTemplateFromDocx({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2048,38 +3532,26 @@ const template = await docuseal.createTemplateFromDocx({ } ``` -### Create a template from existing PDF - -The API endpoint provides the functionality to create a fillable document template for existing 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 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 +### 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.
Related Guides
Create PDF document fillable form with HTML ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ] +const template = await docuseal.createTemplateFromHtml({ + html: `

Lorem Ipsum is simply dummy text of the + + +and typesetting industry

+`, + name: "Test Template" }); ``` @@ -2093,8 +3565,8 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2103,246 +3575,78 @@ const template = await docuseal.createTemplateFromPdf({ "schema": { "type": "object", "required": [ - "documents" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML template of the footer to be displayed on every page." + }, "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", + "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true }, "documents": { "type": "array", + "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ - "name", - "file" + "html" ], "properties": { + "html": { + "type": "string", + "description": "HTML template with field tags.", + "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" + }, "name": { "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "flatten": { - "type": "boolean", - "description": "Remove PDF form fields from the document.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } @@ -2355,6 +3659,72 @@ const template = await docuseal.createTemplateFromPdf({ } ``` +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.cloneTemplate(1000001, { + name: "Cloned Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + ### Merge templates The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. @@ -2444,44 +3814,18 @@ const template = await docuseal.mergeTemplates({ } ``` -### Create a submission from PDF - -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 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 +### Update a template +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromPdf({ - name: "Test Submission Document", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] +const template = await docuseal.updateTemplate(1000001, { + name: "New Document Name", + folder_name: "New Folder" }); ``` @@ -2493,507 +3837,53 @@ const submission = await docuseal.createSubmissionFromPdf({ } ], "tags": [ - "Submissions" + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents", - "submitters" - ], "properties": { "name": { "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" + "description": "The name of the template", + "example": "New Document Name" }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { + "folder_name": { "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" ] }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." - }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - } - } - } - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "flatten": { + "archived": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "description": "Set `false` to unarchive template." } } } @@ -3003,502 +3893,19 @@ const submission = await docuseal.createSubmissionFromPdf({ } ``` -### Create a submission from HTML +### Update template documents -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 +The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromHtml({ - name: "Test Submission Document", +const template = await docuseal.updateTemplateDocuments(1000001, { documents: [ { - name: "Test Document", - html: `

Lorem Ipsum is simply dummy text of the - - -and typesetting industry

-` - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", - "items": { - "type": "object", - "required": [ - "html" - ], - "properties": { - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - }, - "html": { - "type": "string", - "description": "HTML document content with field tags.", - "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" - }, - "html_header": { - "type": "string", - "description": "HTML document content of the header to be displayed on every page." - }, - "html_footer": { - "type": "string", - "description": "HTML document content of the footer to be displayed on every page." - }, - "size": { - "type": "string", - "default": "Letter", - "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", - "enum": [ - "Letter", - "Legal", - "Tabloid", - "Ledger", - "A0", - "A1", - "A2", - "A3", - "A4", - "A5", - "A6" - ], - "example": "A4" - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - } - } - } - } - } - } -} -``` - -### Create a template from PDF - -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 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 - - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", - documents: [ - { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "string" } ] }); @@ -3514,304 +3921,69 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", - "parameters": [], + "summary": "Update template documents", + "operationId": "addDocumentToTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": [ - "documents" - ], "properties": { - "name": { - "type": "string", - "description": "Name of the template", - "example": "Test PDF" - }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be created." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", - "example": "unique-key" - }, - "shared_link": { - "type": "boolean", - "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", - "default": true - }, "documents": { "type": "array", + "description": "The list of documents to add or replace in the template.", "items": { "type": "object", - "required": [ - "name", - "file" - ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, "file": { - "example": "base64", "type": "string", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." }, - "fields": { - "type": "array", - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the field." - }, - "type": { - "type": "string", - "description": "Type of the field (e.g., text, signature, date, initials).", - "enum": [ - "heading", - "text", - "signature", - "initials", - "date", - "number", - "image", - "checkbox", - "multiple", - "file", - "radio", - "select", - "cells", - "stamp", - "payment", - "phone", - "verification" - ] - }, - "role": { - "type": "string", - "description": "Role name of the signer." - }, - "required": { - "type": "boolean", - "description": "Indicates if the field is required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "areas": { - "type": "array", - "items": { - "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], - "properties": { - "x": { - "type": "number", - "description": "X-coordinate of the field area." - }, - "y": { - "type": "number", - "description": "Y-coordinate of the field area." - }, - "w": { - "type": "number", - "description": "Width of the field area." - }, - "h": { - "type": "number", - "description": "Height of the field area." - }, - "page": { - "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 - }, - "option": { - "type": "string", - "description": "Option string value for 'radio' and 'multiple' select field types." - } - } - } - }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." } } } }, - "flatten": { + "merge": { "type": "boolean", - "description": "Remove PDF form fields from the documents.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." } } } @@ -3821,33 +3993,16 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Create a submission from DOCX +### Archive a template -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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
Related Guides
Use embedded text field tags to create a fillable form +The API endpoint allows you to archive a document template. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const submission = await docuseal.createSubmissionFromDocx({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ - { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); +await docuseal.archiveTemplate(1000001); ``` ```json @@ -3858,412 +4013,22 @@ const submission = await docuseal.createSubmissionFromDocx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document submission.", - "example": "Test Submission Document" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } - }, - "order": { - "type": "string", - "description": "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", - "enum": [ - "preserved", - "random" - ] - }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." - }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "expire_at": { - "type": "string", - "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", - "example": "2024-09-01 12:00:00 UTC" - }, - "template_ids": { - "type": "array", - "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", - "items": { - "type": "integer", - "description": "The ID of the template to use for the submission." - } - }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "file": { - "example": "base64", - "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." - }, - "position": { - "type": "integer", - "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." - } - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", - "items": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "role": { - "type": "string", - "description": "The role name or title of the submitter.", - "example": "First Party" - }, - "email": { - "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" - }, - "phone": { - "type": "string", - "description": "The phone number of the submitter, formatted according to the E.164 standard.", - "example": "+1234567890" - }, - "values": { - "type": "object", - "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "completed": { - "type": "boolean", - "description": "Pass `true` to mark submitter as completed and auto-signed via API." - }, - "metadata": { - "type": "object", - "description": "Metadata object with additional submitter information.", - "example": "{ \"customField\": \"value\" }" - }, - "send_email": { - "type": "boolean", - "description": "Set `false` to disable signature request emails sending only for this submitter.", - "default": true - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails for this submitter." - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "order": { - "type": "integer", - "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." - }, - "require_phone_2fa": { - "type": "boolean", - "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", - "default": false - }, - "fields": { - "type": "array", - "description": "A list of configurations for document form fields.", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Document field name.", - "example": "First Name" - }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - } - ], - "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", - "example": "Acme" - }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false - }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." - }, - "title": { - "type": "string", - "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." - }, - "description": { - "type": "string", - "description": "Field description displayed on the signing form. Supports Markdown." - }, - "validation": { - "type": "object", - "properties": { - "pattern": { - "type": "string", - "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", - "example": "[A-Z]{4}" - }, - "message": { - "type": "string", - "description": "A custom error message to display on validation failure." - }, - "min": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Minimum allowed number value or date depending on field type." - }, - "max": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - } - ], - "description": "Maximum allowed number value or date depending on field type." - }, - "step": { - "type": "number", - "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." - } - } - }, - "preferences": { - "type": "object", - "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { - "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] - }, - "font": { - "type": "string", - "description": "Font family of the field value.", - "enum": [ - "Times", - "Helvetica", - "Courier" - ] - }, - "color": { - "type": "string", - "description": "Font color of the field value.", - "enum": [ - "black", - "white", - "blue" - ], - "default": "black" - }, - "align": { - "type": "string", - "description": "Horizontal alignment of the field text value.", - "enum": [ - "left", - "center", - "right" - ], - "default": "left" - }, - "valign": { - "type": "string", - "description": "Vertical alignment of the field text value.", - "enum": [ - "top", - "center", - "bottom" - ], - "default": "center" - }, - "format": { - "type": "string", - "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", - "example": "DD/MM/YYYY" - }, - "price": { - "type": "number", - "description": "Price value of the payment field. Only for payment fields.", - "example": 99.99 - }, - "currency": { - "type": "string", - "description": "Currency value of the payment field. Only for payment fields.", - "enum": [ - "USD", - "EUR", - "GBP", - "CAD", - "AUD" - ], - "default": "USD" - }, - "mask": { - "description": "Set `true` to make sensitive data masked on the document.", - "oneOf": [ - { - "type": "integer" - }, - { - "type": "boolean" - } - ], - "default": false - } - } - } - } - } - }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } - } - } - } - }, - "message": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Custom signature request email subject." - }, - "body": { - "type": "string", - "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." - } - } - }, - "merge_documents": { - "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", - "default": false - }, - "remove_tags": { - "type": "boolean", - "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", - "default": true - } - } - } - } + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 } - } + ] } ``` diff --git a/docs/embedding/form-builder-angular.md b/docs/embedding/form-builder-angular.md index b78fafd2..d4cf5a32 100644 --- a/docs/embedding/form-builder-angular.md +++ b/docs/embedding/form-builder-angular.md @@ -151,7 +151,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "drawFieldType": { @@ -194,7 +195,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -321,7 +323,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -444,6 +447,12 @@ const token = jwt.sign({ "default": true, "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." }, + "withFieldsDetection": { + "type": "boolean", + "required": false, + "default": false, + "description": "Display a button to automatically detect and add fields to the document with AI." + }, "withFieldPlaceholder": { "type": "boolean", "required": false, @@ -483,7 +492,7 @@ const token = jwt.sign({ "type": "string", "required": false, "default": "en", - "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'nl', 'he', 'ar' languages are available." }, "i18n": { "type": "object", diff --git a/docs/embedding/form-builder-javascript.md b/docs/embedding/form-builder-javascript.md index 4953b54f..9d863bd5 100644 --- a/docs/embedding/form-builder-javascript.md +++ b/docs/embedding/form-builder-javascript.md @@ -118,7 +118,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -249,7 +250,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -336,7 +338,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "data-draw-field-type": { @@ -408,6 +411,12 @@ "default": true, "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." }, + "data-with-fields-detection": { + "type": "boolean", + "required": false, + "default": false, + "description": "Display a button to automatically detect and add fields to the document with AI." + }, "data-with-field-placeholder": { "type": "boolean", "required": false, @@ -453,7 +462,7 @@ "type": "string", "required": false, "default": "en", - "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'nl', 'he', 'ar' languages are available." }, "data-background-color": { "type": "string", diff --git a/docs/embedding/form-builder-react.md b/docs/embedding/form-builder-react.md index 894f684a..e6dcac26 100644 --- a/docs/embedding/form-builder-react.md +++ b/docs/embedding/form-builder-react.md @@ -142,7 +142,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "drawFieldType": { @@ -185,7 +186,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -312,7 +314,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -435,6 +438,12 @@ const token = jwt.sign({ "default": true, "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." }, + "withFieldsDetection": { + "type": "boolean", + "required": false, + "default": false, + "description": "Display a button to automatically detect and add fields to the document with AI." + }, "withFieldPlaceholder": { "type": "boolean", "required": false, @@ -474,7 +483,7 @@ const token = jwt.sign({ "type": "string", "required": false, "default": "en", - "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'nl', 'he', 'ar' languages are available." }, "i18n": { "type": "object", diff --git a/docs/embedding/form-builder-vue.md b/docs/embedding/form-builder-vue.md index f745be19..ef5475fc 100644 --- a/docs/embedding/form-builder-vue.md +++ b/docs/embedding/form-builder-vue.md @@ -163,7 +163,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "draw-field-type": { @@ -206,7 +207,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -333,7 +335,8 @@ const token = jwt.sign({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -450,6 +453,12 @@ const token = jwt.sign({ "default": true, "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." }, + "with-fields-detection": { + "type": "boolean", + "required": false, + "default": false, + "description": "Display a button to automatically detect and add fields to the document with AI." + }, "with-field-placeholder": { "type": "boolean", "required": false, @@ -483,7 +492,7 @@ const token = jwt.sign({ "type": "string", "required": false, "default": "en", - "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'nl', 'he', 'ar' languages are available." }, "i18n": { "type": "object", diff --git a/docs/embedding/signing-form-angular.md b/docs/embedding/signing-form-angular.md index 8bbad1a0..16e47593 100644 --- a/docs/embedding/signing-form-angular.md +++ b/docs/embedding/signing-form-angular.md @@ -30,7 +30,7 @@ export class AppComponent {} "src": { "type": "string", "required": true, - "description": "Public URL of the document signing form. There are two types of URLs:
  • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
  • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    • " + "description": "Public URL of the document signing form. There are two types of URLs:
    • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
    • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    " }, "email": { "type": "string", diff --git a/docs/embedding/signing-form-javascript.md b/docs/embedding/signing-form-javascript.md index 935153b5..b0ccf4b9 100644 --- a/docs/embedding/signing-form-javascript.md +++ b/docs/embedding/signing-form-javascript.md @@ -26,7 +26,7 @@ "data-src": { "type": "string", "required": true, - "description": "Public URL of the document signing form. There are two types of URLs:
  • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
  • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    • " + "description": "Public URL of the document signing form. There are two types of URLs:
    • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
    • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    " }, "data-email": { "type": "string", diff --git a/docs/embedding/signing-form-react.md b/docs/embedding/signing-form-react.md index 91039bbf..949adb43 100644 --- a/docs/embedding/signing-form-react.md +++ b/docs/embedding/signing-form-react.md @@ -27,7 +27,7 @@ export function App() { "src": { "type": "string", "required": true, - "description": "Public URL of the document signing form. There are two types of URLs:
  • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
  • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    • " + "description": "Public URL of the document signing form. There are two types of URLs:
    • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
    • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    " }, "email": { "type": "string", diff --git a/docs/embedding/signing-form-vue.md b/docs/embedding/signing-form-vue.md index 45e6a336..6014da83 100644 --- a/docs/embedding/signing-form-vue.md +++ b/docs/embedding/signing-form-vue.md @@ -36,7 +36,7 @@ export default { "src": { "type": "string", "required": true, - "description": "Public URL of the document signing form. There are two types of URLs:
  • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
  • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    • " + "description": "Public URL of the document signing form. There are two types of URLs:
    • /d/{slug} - template form signing URL can be copied from the template page in the admin dashboard. Also template \"slug\" key can be obtained via the /templates API.
    • /s/{slug} - individual signer URL. Signer \"slug\" key can be obtained via the /submissions API which is used to initiate signature requests for a template form with recipients.
    " }, "email": { "type": "string", diff --git a/docs/openapi.json b/docs/openapi.json index 84f95deb..9afd740c 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -251,7 +251,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -277,6 +278,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -300,6 +305,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -714,7 +726,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -740,6 +753,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -763,6 +780,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -1782,6 +1806,11 @@ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -1933,6 +1962,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -1986,6 +2024,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2622,6 +2667,10 @@ "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." + }, + "data": { + "type": "object", + "description": "Additional event details object." } } } @@ -2733,7 +2782,8 @@ "id": 1, "submitter_id": 2, "event_type": "view_form", - "event_timestamp": "2023-12-14T15:47:24.566Z" + "event_timestamp": "2023-12-14T15:47:24.566Z", + "data": {} } ], "documents": [ @@ -3318,7 +3368,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3471,6 +3522,15 @@ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, "fields": { "type": "array", "description": "A list of configurations for document form fields.", @@ -3609,6 +3669,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -3662,6 +3731,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3744,7 +3820,6 @@ "type": "object", "required": [ "id", - "submission_id", "uuid", "email", "slug", @@ -3833,6 +3908,53 @@ "awaiting" ] }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submitter.", + "items": { + "type": "object", + "required": [ + "field", + "value" + ], + "properties": { + "field": { + "type": "string", + "description": "Document template field name." + }, + "value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Pre-filled value of the field." + } + } + } + }, "role": { "type": "string", "description": "The role of the submitter." @@ -3944,7 +4066,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -3970,6 +4093,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -3993,6 +4120,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -4040,27 +4174,6 @@ } } }, - "documents": { - "type": "array", - "description": "List of documents attached to the one-off submission.", - "items": { - "type": "object", - "required": [ - "attachment_uuid", - "name" - ], - "properties": { - "attachment_uuid": { - "type": "string", - "description": "Unique indentifier of attached document to the one-off submission." - }, - "name": { - "type": "string", - "description": "Name of the attached document to the one-off submission." - } - } - } - }, "expire_at": { "type": "string", "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", @@ -4158,7 +4271,7 @@ "Submissions" ], "summary": "Create a submission from DOCX", - "description": "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 for the specific text variable syntax, including dynamic content tables and list. You can also use the {{signature}} fillable field syntax to define fillable fields, as in a PDF.
    Related Guides
    Use embedded text field tags to create a fillable form", + "description": "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 for the specific text variable syntax, including dynamic content tables and list. 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", "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { @@ -4189,7 +4302,7 @@ }, "variables": { "type": "object", - "description": "Dynamic content variables object", + "description": "Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in DOCX.", "example": { "variable_name": "value" } @@ -4327,6 +4440,15 @@ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, "fields": { "type": "array", "description": "A list of configurations for document form fields.", @@ -4465,6 +4587,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -4518,6 +4649,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -4595,7 +4733,6 @@ "type": "object", "required": [ "id", - "submission_id", "uuid", "email", "slug", @@ -4684,6 +4821,53 @@ "awaiting" ] }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submitter.", + "items": { + "type": "object", + "required": [ + "field", + "value" + ], + "properties": { + "field": { + "type": "string", + "description": "Document template field name." + }, + "value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Pre-filled value of the field." + } + } + } + }, "role": { "type": "string", "description": "The role of the submitter." @@ -4795,7 +4979,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -4821,6 +5006,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -4844,6 +5033,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -4891,27 +5087,6 @@ } } }, - "documents": { - "type": "array", - "description": "List of documents attached to the one-off submission.", - "items": { - "type": "object", - "required": [ - "attachment_uuid", - "name" - ], - "properties": { - "attachment_uuid": { - "type": "string", - "description": "Unique indentifier of attached document to the one-off submission." - }, - "name": { - "type": "string", - "description": "Name of the attached document to the one-off submission." - } - } - } - }, "expire_at": { "type": "string", "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", @@ -5198,6 +5373,15 @@ "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, + "require_email_2fa": { + "type": "boolean", + "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", + "default": false + }, + "invite_by": { + "type": "string", + "description": "Set the role name of the previous party that should invite this party via email." + }, "fields": { "type": "array", "description": "A list of configurations for document form fields.", @@ -5336,6 +5520,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -5389,6 +5582,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -5461,7 +5661,6 @@ "type": "object", "required": [ "id", - "submission_id", "uuid", "email", "slug", @@ -5550,6 +5749,53 @@ "awaiting" ] }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submitter.", + "items": { + "type": "object", + "required": [ + "field", + "value" + ], + "properties": { + "field": { + "type": "string", + "description": "Document template field name." + }, + "value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Pre-filled value of the field." + } + } + } + }, "role": { "type": "string", "description": "The role of the submitter." @@ -5661,7 +5907,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -5687,6 +5934,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -5710,6 +5961,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -5757,27 +6015,6 @@ } } }, - "documents": { - "type": "array", - "description": "List of documents attached to the one-off submission.", - "items": { - "type": "object", - "required": [ - "attachment_uuid", - "name" - ], - "properties": { - "attachment_uuid": { - "type": "string", - "description": "Unique indentifier of attached document to the one-off submission." - }, - "name": { - "type": "string", - "description": "Name of the attached document to the one-off submission." - } - } - } - }, "expire_at": { "type": "string", "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", @@ -6078,6 +6315,10 @@ "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." + }, + "data": { + "type": "object", + "description": "Additional event details object." } } } @@ -6185,7 +6426,8 @@ "id": 12, "submitter_id": 7, "event_type": "view_form", - "event_timestamp": "2023-12-14T15:47:17.351Z" + "event_timestamp": "2023-12-14T15:47:17.351Z", + "data": {} } ], "values": [ @@ -6435,6 +6677,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -6488,6 +6739,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -6990,6 +7248,10 @@ "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." + }, + "data": { + "type": "object", + "description": "Additional event details object." } } } @@ -7126,7 +7388,8 @@ "id": 12, "submitter_id": 7, "event_type": "view_form", - "event_timestamp": "2023-12-14T15:48:17.351Z" + "event_timestamp": "2023-12-14T15:48:17.351Z", + "data": {} } ], "values": [ @@ -7346,7 +7609,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -7372,6 +7636,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -7395,6 +7663,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -7793,7 +8068,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -7819,6 +8095,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -7842,6 +8122,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -8294,7 +8581,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -8320,6 +8608,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -8343,6 +8635,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -8674,7 +8973,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -8812,6 +9112,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -8865,6 +9174,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -8989,7 +9305,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -9015,6 +9332,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -9038,6 +9359,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -9369,7 +9697,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -9515,6 +9844,15 @@ ], "default": "black" }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", @@ -9568,6 +9906,13 @@ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -9702,7 +10047,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -9728,6 +10074,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -9751,6 +10101,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, @@ -10169,7 +10526,8 @@ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "required": { @@ -10195,6 +10553,10 @@ "type": "string", "description": "Font color of the field value." }, + "background": { + "type": "string", + "description": "Field box background color." + }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." @@ -10218,6 +10580,13 @@ "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } }, diff --git a/docs/webhooks/submission-webhook.md b/docs/webhooks/submission-webhook.md index 15e1bcbd..8bed4a05 100644 --- a/docs/webhooks/submission-webhook.md +++ b/docs/webhooks/submission-webhook.md @@ -281,6 +281,10 @@ Get submission creation, completion, expiration, and archiving notifications usi "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." + }, + "data": { + "type": "object", + "description": "Additional event details object." } } }