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 | 4040 +++++++-------- docs/api/go.md | 4806 +++++++++--------- docs/api/java.md | 4140 ++++++++------- docs/api/javascript.md | 4957 +++++++++--------- docs/api/nodejs.md | 5527 ++++++++++----------- docs/api/php.md | 4973 +++++++++--------- docs/api/python.md | 5059 +++++++++---------- docs/api/ruby.md | 5059 +++++++++---------- docs/api/shell.md | 4150 ++++++++-------- docs/api/typescript.md | 4957 +++++++++--------- 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, 23192 insertions(+), 25095 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,9 +1,9 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```csharp -var client = new RestClient("https://api.docuseal.com/templates"); +var client = new RestClient("https://api.docuseal.com/submissions"); var request = new RestRequest("", Method.Get); request.AddHeader("X-Auth-Token", "API_KEY"); var response = client.Execute(request); @@ -17,47 +17,62 @@ var response = client.Execute(request); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -66,7 +81,7 @@ var response = client.Execute(request); "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -75,7 +90,7 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -84,7 +99,7 @@ var response = client.Execute(request); "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -93,18 +108,18 @@ var response = client.Execute(request); "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001"); +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); @@ -118,10 +133,10 @@ var response = client.Execute(request); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -130,20 +145,20 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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/templates/1000001"); -var request = new RestRequest("", Method.Delete); +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); ``` @@ -156,10 +171,10 @@ var response = client.Execute(request); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -168,23 +183,23 @@ var response = client.Execute(request); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```csharp -var client = new RestClient("https://api.docuseal.com/templates/1000001"); -var request = new RestRequest("", Method.Put); +var client = new RestClient("https://api.docuseal.com/submissions"); +var request = new RestRequest("", Method.Post); 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); +request.AddParameter("application/json", "{\"template_id\":1000001,\"send_email\":true,\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -196,272 +211,79 @@ var response = client.Execute(request); } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```csharp -var client = new RestClient("https://api.docuseal.com/submissions"); -var request = new RestRequest("", Method.Get); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```csharp -var client = new RestClient("https://api.docuseal.com/submissions"); -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,\"send_email\":true,\"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", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,90 +603,17 @@ 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 - } - ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```csharp -var client = new RestClient("https://api.docuseal.com/submissions/1001"); -var request = new RestRequest("", Method.Delete); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 - } - ] -} -``` +### Create a submission from PDF -### Get submission documents +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 -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); +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); ``` @@ -857,48 +627,8 @@ var response = client.Execute(request); "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -907,861 +637,81 @@ var response = client.Execute(request); "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```csharp -var client = new RestClient("https://api.docuseal.com/submitters/500001"); -var request = new RestRequest("", Method.Get); -request.AddHeader("X-Auth-Token", "API_KEY"); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```csharp -var client = new RestClient("https://api.docuseal.com/submitters/500001"); -var request = new RestRequest("", Method.Put); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template 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." - }, - "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 - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```csharp -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); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```csharp -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", "{\"documents\":[{\"file\":\"string\"}]}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "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. - -```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." - } - } - } - } - } - } -} -``` - -### 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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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": "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." - }, - "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": [ - "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": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - } - } - } - } - } - } - } - } - } -} -``` - -### 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 - - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/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 DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```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." + "description": "Name of the document." }, "file": { - "type": "string", "example": "base64", + "type": "string", "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", "properties": { @@ -1789,7 +739,8 @@ var response = client.Execute(request); "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -1812,6 +763,13 @@ var response = client.Execute(request); "type": "array", "items": { "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], "properties": { "x": { "type": "number", @@ -1831,7 +789,8 @@ var response = client.Execute(request); }, "page": { "type": "integer", - "description": "Page number of the field area. Starts from 1." + "description": "Page number of the field area. Starts from 1.", + "example": 1 }, "option": { "type": "string", @@ -1850,6 +809,160 @@ var response = client.Execute(request); "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", @@ -1927,6 +1040,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,14 +1102,56 @@ var response = client.Execute(request); } ], "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 } } } @@ -1997,17 +1161,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 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/templates/pdf"); +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 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\":\"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); ``` @@ -2019,10 +1182,10 @@ var response = client.Execute(request); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -2031,22 +1194,65 @@ var response = client.Execute(request); "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_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 + }, + "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": "The folder's name to which the template should be created." + "description": "Specify Reply-To address to use in the notification emails." }, - "external_id": { + "expire_at": { "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" + "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", @@ -2065,48 +1271,150 @@ var response = client.Execute(request); "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." + }, + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2116,56 +1424,45 @@ var response = client.Execute(request); "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", @@ -2203,6 +1500,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.", @@ -2256,108 +1562,51 @@ var response = client.Execute(request); } ], "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 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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. - -```csharp -var client = new RestClient("https://api.docuseal.com/templates/merge"); -var request = new RestRequest("", Method.Post); -request.AddHeader("X-Auth-Token", "API_KEY"); -request.AddHeader("content-type", "application/json"); -request.AddParameter("application/json", "{\"template_ids\":[321,432],\"name\":\"Merged Template\"}", ParameterType.RequestBody); -var response = client.Execute(request); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." + "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}}." + } + } }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false }, - "shared_link": { + "remove_tags": { "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.", + "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] } } } @@ -2367,17 +1616,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 +### 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/pdf"); +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\":\"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); +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); ``` @@ -2391,8 +1639,8 @@ var response = client.Execute(request); "tags": [ "Submissions" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2407,7 +1655,7 @@ var response = client.Execute(request); "properties": { "name": { "type": "string", - "description": "Name of the document submission.", + "description": "Name of the document submission", "example": "Test Submission Document" }, "send_email": { @@ -2456,125 +1704,49 @@ var response = client.Execute(request); }, "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": [ - "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" - ] - } - } - } + "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", @@ -2656,6 +1828,15 @@ 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 + }, + "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.", @@ -2794,6 +1975,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.", @@ -2847,6 +2037,13 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2876,20 +2073,10 @@ var response = client.Execute(request); } } }, - "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 } } } @@ -2899,16 +2086,206 @@ var response = client.Execute(request); } ``` -### Create a submission from HTML +### Archive a submission + +The API endpoint allows you to archive a submission. + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/1001"); +var request = new RestRequest("", Method.Delete); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +The API endpoint provides the ability to retrieve a list of submitters. + +```csharp +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); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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." + } + ] +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```csharp +var client = new RestClient("https://api.docuseal.com/submitters/500001"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter -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 update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/html"); -var request = new RestRequest("", Method.Post); +var client = new RestClient("https://api.docuseal.com/submitters/500001"); +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\":\"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); +request.AddParameter("application/json", "{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -2920,212 +2297,124 @@ var response = client.Execute(request); } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number 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": { + "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\" }" + }, + "completed_redirect_url": { "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" + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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." - } + "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 }, - "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." - } + "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}}." } } }, - "submitters": { + "fields": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "email" + "name" ], "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 + "description": "Document template field name.", + "example": "First Name" }, - "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": { + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { "oneOf": [ { "type": "string" @@ -3135,206 +2424,173 @@ var response = client.Execute(request); }, { "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." } + ] + } + } + ], + "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." + }, + "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" } - }, - "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 - } + ], + "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 } } } @@ -3344,6 +2600,145 @@ var response = client.Execute(request); } ``` +### 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 + } + ] +} +``` + ### 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 @@ -3449,7 +2844,8 @@ var response = client.Execute(request); "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3595,6 +2991,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.", @@ -3648,6 +3053,13 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3675,16 +3087,17 @@ var response = client.Execute(request); } ``` -### Create a submission from DOCX +### 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 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 ```csharp -var client = new RestClient("https://api.docuseal.com/submissions/docx"); +var client = new RestClient("https://api.docuseal.com/templates/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); +request.AddParameter("application/json", "{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}", ParameterType.RequestBody); var response = client.Execute(request); ``` @@ -3696,10 +3109,10 @@ var response = client.Execute(request); } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3708,65 +3121,27 @@ var response = client.Execute(request); "schema": { "type": "object", "required": [ - "documents", - "submitters" + "documents" ], "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." + "description": "Name of the template", + "example": "Test DOCX" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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", @@ -3782,144 +3157,52 @@ var response = client.Execute(request); "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "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 + "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", - "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" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3929,6 +3212,49 @@ var response = client.Execute(request); "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": { @@ -4005,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.", @@ -4058,44 +3393,459 @@ var response = client.Execute(request); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } } } + } + } + } + } + } + } + } + } + } +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### 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. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/merge"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"template_ids\":[321,432],\"name\":\"Merged Template\"}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```csharp +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", "{\"documents\":[{\"file\":\"string\"}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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,6 +1,6 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```go package main @@ -13,7 +13,7 @@ import ( func main() { - url := "https://api.docuseal.com/templates" + url := "https://api.docuseal.com/submissions" req, _ := http.NewRequest("GET", url, nil) @@ -38,47 +38,62 @@ func main() { } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -87,7 +102,7 @@ func main() { "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -96,7 +111,7 @@ func main() { "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -105,7 +120,7 @@ func main() { "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -114,15 +129,15 @@ func main() { "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```go package main @@ -135,7 +150,7 @@ import ( func main() { - url := "https://api.docuseal.com/templates/1000001" + url := "https://api.docuseal.com/submissions/1001" req, _ := http.NewRequest("GET", url, nil) @@ -160,10 +175,10 @@ func main() { } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -172,16 +187,16 @@ func main() { "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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 @@ -194,9 +209,9 @@ import ( func main() { - url := "https://api.docuseal.com/templates/1000001" + url := "https://api.docuseal.com/submissions/1001/documents" - req, _ := http.NewRequest("DELETE", url, nil) + req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Auth-Token", "API_KEY") @@ -219,10 +234,10 @@ func main() { } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -231,16 +246,16 @@ func main() { "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```go package main @@ -254,11 +269,11 @@ import ( func main() { - url := "https://api.docuseal.com/templates/1000001" + url := "https://api.docuseal.com/submissions" - payload := strings.NewReader("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") + payload := strings.NewReader("{\"template_id\":1000001,\"send_email\":true,\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") - req, _ := http.NewRequest("PUT", url, payload) + req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Auth-Token", "API_KEY") req.Header.Add("content-type", "application/json") @@ -282,316 +297,79 @@ func main() { } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submissions" - - 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": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submissions" - - payload := strings.NewReader("{\"template_id\":1000001,\"send_email\":true,\"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", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,189 +736,8 @@ 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 - } - ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submissions/1001" - - 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": [ - "Submissions" - ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -1123,1055 +746,324 @@ func main() { "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submitters/500001" - - 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": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submitters/500001" - - payload := strings.NewReader("{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}") - - 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": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "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." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "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\" }" - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 - }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template 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." + "description": "Name of the document." }, - "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." - } - } + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, - "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" + "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." + } + } } - ], - "default": false + }, + "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." } } } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```go -package main - -import ( - "fmt" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/submitters" - - 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": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/1000001/documents" - - payload := strings.NewReader("{\"documents\":[{\"file\":\"string\"}]}") - - 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 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": { + }, + "submitters": { "type": "array", - "description": "The list of documents to add or replace in the template.", + "description": "The list of submitters for the submission.", "items": { "type": "object", + "required": [ + "email" + ], "properties": { "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "The name of the submitter." }, - "file": { + "role": { "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": "The role name or title of the submitter.", + "example": "First Party" }, - "html": { + "email": { "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." + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" }, - "position": { + "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": "Position of the document. By default will be added as the last document in the template.", - "example": 0 + "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." }, - "replace": { + "require_phone_2fa": { "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." + "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 }, - "remove": { + "require_email_2fa": { "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. - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/1000001/clone" - - payload := strings.NewReader("{\"name\":\"Cloned Template\"}") - - 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": "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 - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/html" - - payload := strings.NewReader("{\"html\":\"

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

\\n\",\"name\":\"Test Template\"}") - - 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 HTML", - "operationId": "createTemplateFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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": "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." - }, - "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": [ - "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" + "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 }, - "name": { + "invite_by": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - } - } - } - } - } - } - } - } - } -} -``` - -### 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" + "description": "Set the role name of the previous party that should invite this party via email." }, "fields": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2181,49 +1073,6 @@ func main() { "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": { @@ -2300,6 +1149,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.", @@ -2353,14 +1211,56 @@ func main() { } ], "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 } } } @@ -2370,10 +1270,9 @@ func main() { } ``` -### 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 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 @@ -2387,9 +1286,9 @@ import ( func main() { - url := "https://api.docuseal.com/templates/pdf" + url := "https://api.docuseal.com/submissions/docx" - 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}]}]}]}") + 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) @@ -2415,10 +1314,10 @@ func main() { } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -2427,33 +1326,76 @@ func main() { "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_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 + }, + "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": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "description": "Specify URL to redirect to after the submission completion." }, - "documents": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "file" - ], - "properties": { - "name": { + "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." }, @@ -2461,48 +1403,150 @@ func main() { "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." + }, + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2512,75 +1556,64 @@ func main() { "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": { + "validation": { "type": "object", "properties": { - "font_size": { - "type": "integer", - "description": "Font size of the field value in pixels.", - "example": 12 - }, - "font_type": { + "pattern": { "type": "string", - "description": "Font type of the field value.", - "enum": [ - "bold", - "italic", - "bold_italic" - ] + "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", + "example": "[A-Z]{4}" }, - "font": { + "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": [ @@ -2599,6 +1632,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.", @@ -2652,131 +1694,51 @@ func main() { } ], "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 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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. - -```go -package main - -import ( - "fmt" - "strings" - "net/http" - "io" -) - -func main() { - - url := "https://api.docuseal.com/templates/merge" - - payload := strings.NewReader("{\"template_ids\":[321,432],\"name\":\"Merged Template\"}") - - 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": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." + "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}}." + } + } }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false }, - "shared_link": { + "remove_tags": { "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.", + "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] } } } @@ -2786,10 +1748,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 +### 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 @@ -2803,9 +1764,9 @@ import ( func main() { - url := "https://api.docuseal.com/submissions/pdf" + url := "https://api.docuseal.com/submissions/html" - 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\":\"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) @@ -2833,8 +1794,8 @@ func main() { "tags": [ "Submissions" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2849,7 +1810,7 @@ func main() { "properties": { "name": { "type": "string", - "description": "Name of the document submission.", + "description": "Name of the document submission", "example": "Test Submission Document" }, "send_email": { @@ -2898,125 +1859,49 @@ func main() { }, "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": [ - "name", - "file" + "html" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" }, - "file": { - "example": "base64", + "html": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "HTML document content with field tags.", + "example": "

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

\n" }, - "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" - ] - } - } - } + "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", @@ -3098,6 +1983,15 @@ 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 + }, + "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.", @@ -3236,6 +2130,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.", @@ -3289,6 +2192,13 @@ func main() { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3318,20 +2228,10 @@ func main() { } } }, - "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 } } } @@ -3341,30 +2241,26 @@ func main() { } ``` -### Create a submission from HTML +### Archive a submission -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 archive a submission. ```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\"}]}") + url := "https://api.docuseal.com/submissions/1001" - req, _ := http.NewRequest("POST", url, payload) + req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("X-Auth-Token", "API_KEY") - req.Header.Add("content-type", "application/json") res, _ := http.DefaultClient.Do(req) @@ -3387,210 +2283,379 @@ func main() { "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": { + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +The API endpoint provides the ability to retrieve a list of submitters. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submitters" + + 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": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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." + } + ] +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submitters/500001" + + 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": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submitters/500001" + + payload := strings.NewReader("{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}") + + 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": [ + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "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." + }, + "send_email": { + "type": "boolean", + "description": "Set `true` to re-send signature request emails." + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to re-send signature request via phone number SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "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\" }" + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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 + }, + "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}}." + } + } + }, + "fields": { + "type": "array", + "description": "A list of configurations for template document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { "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 + "description": "Document template field name.", + "example": "First Name" }, - "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": { + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { "oneOf": [ { "type": "string" @@ -3600,212 +2665,360 @@ func main() { }, { "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 } + ] + } + } + ], + "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." + }, + "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." } } }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" + "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" + } + } } } } } - }, - "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 } } } } } - } + } +} +``` + +### 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 + } + ] } ``` @@ -3937,7 +3150,8 @@ func main() { "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -4083,6 +3297,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.", @@ -4136,6 +3359,13 @@ func main() { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -4163,9 +3393,10 @@ func main() { } ``` -### Create a submission from DOCX +### 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 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 ```go package main @@ -4179,9 +3410,9 @@ import ( func main() { - url := "https://api.docuseal.com/submissions/docx" + url := "https://api.docuseal.com/templates/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\"}]}") + payload := strings.NewReader("{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}") req, _ := http.NewRequest("POST", url, payload) @@ -4207,10 +3438,10 @@ func main() { } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -4219,65 +3450,27 @@ func main() { "schema": { "type": "object", "required": [ - "documents", - "submitters" + "documents" ], "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." + "description": "Name of the template", + "example": "Test DOCX" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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", @@ -4290,147 +3483,55 @@ func main() { "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." + "description": "Name of the document." }, - "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 + "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", - "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" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -4440,6 +3541,49 @@ func main() { "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": { @@ -4516,6 +3660,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.", @@ -4569,44 +3722,574 @@ func main() { } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } } } + } + } + } + } + } + } + } + } + } +} +``` + +### 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 + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/html" + + payload := strings.NewReader("{\"html\":\"

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

\\n\",\"name\":\"Test Template\"}") + + 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 HTML", + "operationId": "createTemplateFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001/clone" + + payload := strings.NewReader("{\"name\":\"Cloned Template\"}") + + 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": "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. + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/merge" + + payload := strings.NewReader("{\"template_ids\":[321,432],\"name\":\"Merged Template\"}") + + 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": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001/documents" + + payload := strings.NewReader("{\"documents\":[{\"file\":\"string\"}]}") + + 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 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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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,9 +1,9 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```java -HttpResponse response = Unirest.get("https://api.docuseal.com/templates") +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions") .header("X-Auth-Token", "API_KEY") .asString(); ``` @@ -16,47 +16,62 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates" } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -65,7 +80,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates" "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -74,7 +89,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates" "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -83,7 +98,7 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates" "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -92,18 +107,18 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates" "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```java -HttpResponse response = Unirest.get("https://api.docuseal.com/templates/1000001") +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001") .header("X-Auth-Token", "API_KEY") .asString(); ``` @@ -116,10 +131,10 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates/ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -128,19 +143,19 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/templates/ "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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.delete("https://api.docuseal.com/templates/1000001") +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001/documents") .header("X-Auth-Token", "API_KEY") .asString(); ``` @@ -153,10 +168,10 @@ HttpResponse response = Unirest.delete("https://api.docuseal.com/templat } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -165,22 +180,22 @@ HttpResponse response = Unirest.delete("https://api.docuseal.com/templat "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```java -HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001") +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions") .header("X-Auth-Token", "API_KEY") .header("content-type", "application/json") - .body("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") + .body("{\"template_id\":1000001,\"send_email\":true,\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") .asString(); ``` @@ -192,270 +207,79 @@ HttpResponse response = Unirest.put("https://api.docuseal.com/templates/ } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submissions") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"template_id\":1000001,\"send_email\":true,\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,87 +599,16 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ``` -### 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 - } - ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```java -HttpResponse response = Unirest.delete("https://api.docuseal.com/submissions/1001") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 - } - ] -} -``` +### Create a submission from PDF -### Get submission documents +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 -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") +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(); ``` @@ -848,47 +622,8 @@ HttpResponse response = Unirest.get("https://api.docuseal.com/submission "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -897,891 +632,324 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submitters/500001") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```java -HttpResponse response = Unirest.put("https://api.docuseal.com/submitters/500001") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template 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" + "description": "Name of the document." }, - "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." - }, - "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 - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```java -HttpResponse response = Unirest.get("https://api.docuseal.com/submitters") - .header("X-Auth-Token", "API_KEY") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```java -HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001/documents") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"documents\":[{\"file\":\"string\"}]}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "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. - -```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." - } - } - } - } - } - } -} -``` - -### 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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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": "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." - }, - "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": [ - "html" - ], - "properties": { - "html": { + "file": { + "example": "base64", "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/docx") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}") - .asString(); -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "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." }, - "file": { + "completed_redirect_url": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1791,49 +959,6 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "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": { @@ -1910,6 +1035,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,14 +1097,56 @@ 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" + } } } } } } + }, + "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 } } } @@ -1980,16 +1156,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 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/templates/pdf") +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/docx") .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\":\"Test Submission Document\",\"variables\":{\"variable_name\":\"value\"},\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") .asString(); ``` @@ -2001,10 +1176,10 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -2013,22 +1188,65 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_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 + }, + "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": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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", @@ -2047,48 +1265,150 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "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." + }, + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2098,57 +1418,46 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "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." - } + "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." } } }, - "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": { @@ -2182,8 +1491,17 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "black", "white", "blue" - ], - "default": "black" + ], + "default": "black" + }, + "background": { + "type": "string", + "description": "Field box background color.", + "enum": [ + "black", + "white", + "blue" + ] }, "align": { "type": "string", @@ -2238,107 +1556,51 @@ 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" + } } } } } } }, - "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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. - -```java -HttpResponse response = Unirest.post("https://api.docuseal.com/templates/merge") - .header("X-Auth-Token", "API_KEY") - .header("content-type", "application/json") - .body("{\"template_ids\":[321,432],\"name\":\"Merged Template\"}") - .asString(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." + "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}}." + } + } }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false }, - "shared_link": { + "remove_tags": { "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.", + "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] } } } @@ -2348,16 +1610,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 +### 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/pdf") +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\":\"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\"}]}") + .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(); ``` @@ -2371,8 +1632,8 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "tags": [ "Submissions" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2387,7 +1648,7 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "properties": { "name": { "type": "string", - "description": "Name of the document submission.", + "description": "Name of the document submission", "example": "Test Submission Document" }, "send_email": { @@ -2427,134 +1688,58 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "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" - ] - } - } - } + "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", @@ -2636,6 +1821,15 @@ 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 + }, + "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.", @@ -2774,6 +1968,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.", @@ -2827,6 +2030,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" + } } } } @@ -2856,38 +2066,215 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } } }, - "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 } } } } } - } + } +} +``` + +### Archive a submission + +The API endpoint allows you to archive a submission. + +```java +HttpResponse response = Unirest.delete("https://api.docuseal.com/submissions/1001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +The API endpoint provides the ability to retrieve a list of submitters. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/submitters") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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." + } + ] +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/submitters/500001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] } ``` -### Create a submission from HTML +### Update a submitter -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 update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/html") +HttpResponse response = Unirest.put("https://api.docuseal.com/submitters/500001") .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\"}]}") + .body("{\"email\":\"john.doe@example.com\",\"fields\":[{\"name\":\"First Name\",\"default_value\":\"Acme\"}]}") .asString(); ``` @@ -2899,212 +2286,124 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number 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": { + "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\" }" + }, + "completed_redirect_url": { "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" + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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." - } + "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 }, - "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." - } + "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}}." } } }, - "submitters": { + "fields": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "email" + "name" ], "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 + "description": "Document template field name.", + "example": "First Name" }, - "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": { + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { "oneOf": [ { "type": "string" @@ -3114,206 +2413,173 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio }, { "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." } + ] + } + } + ], + "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." + }, + "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" } - }, - "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 - } + ], + "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 } } } @@ -3323,6 +2589,143 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ``` +### 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 + } + ] +} +``` + ### 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 @@ -3427,7 +2830,8 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3573,6 +2977,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.", @@ -3626,6 +3039,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" + } } } } @@ -3653,15 +3073,16 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` -### Create a submission from DOCX +### 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 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 ```java -HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/docx") +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/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\"}]}") + .body("{\"name\":\"Test DOCX\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\"}]}") .asString(); ``` @@ -3673,10 +3094,10 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3685,65 +3106,27 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "schema": { "type": "object", "required": [ - "documents", - "submitters" + "documents" ], "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." + "description": "Name of the template", + "example": "Test DOCX" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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", @@ -3759,144 +3142,52 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "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 + "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", - "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" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3906,6 +3197,49 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/submissio "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": { @@ -3982,6 +3316,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.", @@ -4035,44 +3378,454 @@ 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" + } } } } } } + } + } + } + } + } + } + } + } + } +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### 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. + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/merge") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"template_ids\":[321,432],\"name\":\"Merged Template\"}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```java +HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001/documents") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"documents\":[{\"file\":\"string\"}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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,13 +1,13 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); ``` ```json @@ -18,47 +18,62 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -67,7 +82,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -76,7 +91,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -85,7 +100,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -94,22 +109,22 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +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 template = await docuseal.getTemplate(1000001); +const submission = await docuseal.getSubmission(1001); ``` ```json @@ -120,10 +135,10 @@ const template = await docuseal.getTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -132,23 +147,23 @@ const template = await docuseal.getTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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" }); -await docuseal.archiveTemplate(1000001); +const submission = await docuseal.getSubmissionDocuments(1001); ``` ```json @@ -159,10 +174,10 @@ await docuseal.archiveTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -171,25 +186,31 @@ await docuseal.archiveTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```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" +const submission = await docuseal.createSubmission({ + template_id: 1000001, + send_email: true, + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] }); ``` @@ -201,281 +222,79 @@ const template = await docuseal.updateTemplate(1000001, { } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submission = await docuseal.createSubmission({ - template_id: 1000001, - send_email: true, - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,55 +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); -``` - -```json -{ - "security": [ +const submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ { - "AuthToken": [] + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ], - "tags": [ - "Submissions" - ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + submitters: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + role: "First Party", + email: "john.doe@example.com" } ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -await docuseal.archiveSubmission(1001); +}); ``` ```json @@ -835,89 +665,8 @@ await docuseal.archiveSubmission(1001); "tags": [ "Submissions" ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -926,231 +675,286 @@ const submission = await docuseal.createSubmissionFromEmails({ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submitter = await docuseal.getSubmitter(500001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submitter = await docuseal.updateSubmitter(500001, { - email: "john.doe@example.com", - fields: [ - { - name: "First Name", - default_value: "Acme" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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." + } }, - "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}}." + "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." + } } } }, - "fields": { + "submitters": { "type": "array", - "description": "A list of configurations for template document form fields.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name" + "email" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "The name of the submitter." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { + "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" @@ -1160,157 +964,232 @@ const submitter = await docuseal.updateSubmitter(500001, { }, { "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." } - ] - } - } - ], - "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." - }, - "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" + }, + "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" + } + } } - ], - "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 } } } @@ -1320,134 +1199,30 @@ const submitter = await docuseal.updateSubmitter(500001, { } ``` -### List all submitters +### Create a submission from DOCX -The API endpoint provides the ability to retrieve a list of submitters. +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 { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); -``` - -```json -{ - "security": [ +const submission = await docuseal.createSubmissionFromDocx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ { - "AuthToken": [] + name: "string", + file: "base64" } ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.updateTemplateDocuments(1000001, { - documents: [ + submitters: [ { - file: "string" + role: "First Party", + email: "john.doe@example.com" } ] }); @@ -1461,395 +1236,239 @@ 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 - } + "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": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true }, - "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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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" + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." + "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" + } }, - "html_footer": { + "order": { "type": "string", - "description": "HTML template of the footer to be displayed on every page." + "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" + ] }, - "name": { + "completed_redirect_url": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Specify URL to redirect to after the submission completion." }, - "size": { + "bcc_completed": { "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" + "description": "Specify BCC address to send signed documents to after the completion." }, - "external_id": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "folder_name": { + "expire_at": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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 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": { + "name": { "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "description": "Name of the document." }, - "name": { + "file": { + "example": "base64", "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```javascript -const docuseal = require("@docuseal/api"); - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromDocx({ - name: "Test DOCX", - documents: [ - { - name: "string", - file: "base64" - } - ] -}); -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { + "role": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1859,49 +1478,6 @@ const template = await docuseal.createTemplateFromDocx({ "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": { @@ -1978,6 +1554,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,53 +1616,89 @@ const template = await docuseal.createTemplateFromDocx({ } ], "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" + } } } } - } - } - } - } - } - } -} -``` - -### 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 + }, + "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 template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", documents: [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + name: "Test Document", + html: `

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

+` + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] }); @@ -2091,10 +1712,10 @@ const template = await docuseal.createTemplateFromPdf({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2103,82 +1724,247 @@ const template = await docuseal.createTemplateFromPdf({ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission", + "example": "Test Submission Document" }, - "folder_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": { "type": "string", - "description": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { - "example": "base64", + "role": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", - "properties": { + "required": [ + "name" + ], + "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2188,57 +1974,46 @@ const template = await docuseal.createTemplateFromPdf({ "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." - } + "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." } } }, - "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": { @@ -2275,6 +2050,15 @@ const template = await docuseal.createTemplateFromPdf({ ], "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.", @@ -2328,24 +2112,46 @@ const template = await docuseal.createTemplateFromPdf({ } ], "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 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 + "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 } } } @@ -2355,22 +2161,55 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Merge templates +### Archive a submission -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. +The API endpoint allows you to archive a submission. ```javascript const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.mergeTemplates({ - template_ids: [ - 321, - 432 +await docuseal.archiveSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } ], - name: "Merged Template" -}); + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +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 { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); ``` ```json @@ -2381,105 +2220,155 @@ const template = await docuseal.mergeTemplates({ } ], "tags": [ - "Templates" + "Submitters" ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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 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 +### Get a submitter +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. ```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: [ +const submitter = await docuseal.getSubmitter(500001); +``` + +```json +{ + "security": [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + "AuthToken": [] } ], - submitters: [ + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ { - role: "First Party", - email: "john.doe@example.com" + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submitter = await docuseal.updateSubmitter(500001, { + email: "john.doe@example.com", + fields: [ + { + name: "First Name", + default_value: "Acme" } ] }); @@ -2493,507 +2382,300 @@ const submission = await docuseal.createSubmissionFromPdf({ } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, - "order": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" }, - "reply_to": { + "completed_redirect_url": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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" + "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 }, - "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." + "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}}." + } } }, - "documents": { + "fields": { "type": "array", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name", - "file" + "name" ], "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." + "description": "Document template field name.", + "example": "First 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" - ] - }, - "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." - } + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" } - } - }, - "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 + ], + "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" }, - "send_sms": { + "readonly": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "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." + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." }, - "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." - } + "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" } - }, - "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 - } + ], + "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." } } }, - "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}}." + "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 - }, - "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 } } } @@ -3003,38 +2685,118 @@ const submission = await docuseal.createSubmissionFromPdf({ } ``` -### Create a submission from HTML +### List all templates -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 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 submission = await docuseal.createSubmissionFromHtml({ - name: "Test Submission Document", - documents: [ +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +``` + +```json +{ + "security": [ { - name: "Test Document", - html: `

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

-` + "AuthToken": [] } ], - submitters: [ + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ { - role: "First Party", - email: "john.doe@example.com" + "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 @@ -3045,250 +2807,162 @@ and typesetting industry

} ], "tags": [ - "Submissions" + "Templates" ], - "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": { + "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: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "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": "Specify BCC address to send signed documents to after the completion." + "description": "Name of the template", + "example": "Test PDF" }, - "reply_to": { + "folder_name": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "The folder's name to which the template should be created." }, - "expire_at": { + "external_id": { "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" + "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" }, - "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." - } + "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 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" + "name", + "file" ], "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." + "description": "Name of the document." }, - "completed_redirect_url": { + "file": { + "example": "base64", "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 + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", - "description": "A list of configurations for document form fields.", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { "type": "string", - "description": "Document field name.", - "example": "First Name" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3298,6 +2972,57 @@ and typesetting industry

"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": { @@ -3374,6 +3099,15 @@ and typesetting industry

], "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.", @@ -3427,39 +3161,31 @@ and typesetting industry

} ], "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": { + "flatten": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", + "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 } } } @@ -3469,9 +3195,9 @@ and typesetting industry

} ``` -### Create a template from PDF +### Create a template from Word DOCX -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 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 ```javascript @@ -3479,26 +3205,12 @@ const docuseal = require("@docuseal/api"); docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", +const template = await docuseal.createTemplateFromDocx({ + name: "Test DOCX", documents: [ { name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "base64" } ] }); @@ -3514,8 +3226,8 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3530,17 +3242,17 @@ const template = await docuseal.createTemplateFromPdf({ "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." + "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 PDF.", + "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.", @@ -3560,14 +3272,14 @@ const template = await docuseal.createTemplateFromPdf({ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the DOCX file or downloadable file URL" }, "fields": { - "type": "array", "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", "items": { "type": "object", "properties": { @@ -3595,7 +3307,8 @@ const template = await docuseal.createTemplateFromPdf({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3618,13 +3331,6 @@ const template = await docuseal.createTemplateFromPdf({ "type": "array", "items": { "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], "properties": { "x": { "type": "number", @@ -3644,8 +3350,7 @@ const template = await docuseal.createTemplateFromPdf({ }, "page": { "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 + "description": "Page number of the field area. Starts from 1." }, "option": { "type": "string", @@ -3741,6 +3446,15 @@ const template = await docuseal.createTemplateFromPdf({ ], "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.", @@ -3794,6 +3508,13 @@ const template = await docuseal.createTemplateFromPdf({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3802,16 +3523,6 @@ const template = await docuseal.createTemplateFromPdf({ } } } - }, - "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 } } } @@ -3821,47 +3532,41 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Create a submission from DOCX +### Create a template from HTML -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 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 submission = await docuseal.createSubmissionFromDocx({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ +const template = await docuseal.createTemplateFromHtml({ + html: `

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

+`, + name: "Test Template" +}); +``` + +```json +{ + "security": [ { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] + "AuthToken": [] } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -3870,394 +3575,415 @@ const submission = await docuseal.createSubmissionFromDocx({ "schema": { "type": "object", "required": [ - "documents", - "submitters" + "html" ], "properties": { - "name": { + "html": { "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 + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." }, - "order": { + "html_footer": { "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": "HTML template of the footer to be displayed on every page." }, - "completed_redirect_url": { + "name": { "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, - "bcc_completed": { + "size": { "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "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" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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": { - "name": { + "html": { "type": "string", - "description": "Name of the document." + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "file": { - "example": "base64", + "name": { "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." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } + } + } + } + } + } + } +} +``` + +### 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" }, - "submitters": { + "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. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.mergeTemplates({ + template_ids: [ + 321, + 432 + ], + name: "Merged Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "An array of template ids to merge into a new template.", "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 - } - } - } - } - } + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.updateTemplateDocuments(1000001, { + documents: [ + { + file: "string" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4267,3 +3993,42 @@ const submission = await docuseal.createSubmissionFromDocx({ } ``` +### 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 + } + ] +} +``` + 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,11 +1,11 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates", { +const resp = await fetch("https://api.docuseal.com/submissions", { method: "GET", headers: { "X-Auth-Token": "API_KEY" @@ -23,47 +23,62 @@ const { data, pagination } = await resp.json(); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -72,7 +87,7 @@ const { data, pagination } = await resp.json(); "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -81,7 +96,7 @@ const { data, pagination } = await resp.json(); "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -90,7 +105,7 @@ const { data, pagination } = await resp.json(); "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -99,27 +114,27 @@ const { data, pagination } = await resp.json(); "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +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/templates/1000001", { +const resp = await fetch("https://api.docuseal.com/submissions/1001", { method: "GET", headers: { "X-Auth-Token": "API_KEY" } }); -const template = await resp.json(); +const submission = await resp.json(); ``` ```json @@ -130,10 +145,10 @@ const template = await resp.json(); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -142,28 +157,28 @@ const template = await resp.json(); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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/templates/1000001", { - method: "DELETE", +const resp = await fetch("https://api.docuseal.com/submissions/1001/documents", { + method: "GET", headers: { "X-Auth-Token": "API_KEY" } }); -await resp.json(); +const submission = await resp.json(); ``` ```json @@ -174,10 +189,10 @@ await resp.json(); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -186,32 +201,38 @@ await resp.json(); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/templates/1000001", { - method: "PUT", +const resp = await fetch("https://api.docuseal.com/submissions", { + method: "POST", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "New Document Name", - folder_name: "New Folder" + template_id: 1000001, + send_email: true, + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] }) }); -const template = await resp.json(); +const submitters = await resp.json(); ``` ```json @@ -222,292 +243,79 @@ const template = await resp.json(); } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions", { - method: "GET", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -const { data, pagination } = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - template_id: 1000001, - send_email: true, - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] - }) -}); - -const submitters = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,144 +692,8 @@ 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 - } - ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions/1001", { - method: "DELETE", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -979,970 +702,324 @@ const submitters = await resp.json(); "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submitters/500001", { - method: "GET", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -const submitter = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submitters/500001", { - method: "PUT", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - email: "john.doe@example.com", - fields: [ - { - name: "First Name", - default_value: "Acme" - } - ] - }) -}); - -const submitter = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." - }, - "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." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false - }, - "reply_to": { - "type": "string", - "description": "Specify Reply-To address to use in the notification emails." - }, - "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\" }" - }, - "completed_redirect_url": { - "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 - }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "Name of the document." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" + "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" ] } } - ], - "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." + } }, - "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 - } - } + "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." } } } - } - } - } - } - } - } -} -``` - -### List all submitters - -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/submitters", { - method: "GET", - headers: { - "X-Auth-Token": "API_KEY" - } -}); - -const { data, pagination } = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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/1000001/documents", { - method: "PUT", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - documents: [ - { - file: "string" - } - ] - }) -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "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": { + }, + "submitters": { "type": "array", - "description": "The list of documents to add or replace in the template.", + "description": "The list of submitters for the submission.", "items": { "type": "object", + "required": [ + "email" + ], "properties": { "name": { "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "The name of the submitter." }, - "file": { + "role": { "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": "The role name or title of the submitter.", + "example": "First Party" }, - "html": { + "email": { "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." + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" }, - "position": { + "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": "Position of the document. By default will be added as the last document in the template.", - "example": 0 + "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." }, - "replace": { + "require_phone_2fa": { "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." + "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 }, - "remove": { + "require_email_2fa": { "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. - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/1000001/clone", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Cloned Template" - }) -}); - -const template = await resp.json(); -``` - -```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 - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/html", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - html: `

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

-`, - name: "Test Template" - }) -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Create a template from HTML", - "operationId": "createTemplateFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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": "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." - }, - "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": [ - "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": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" - } - } - } - } - } - } - } - } - } -} -``` - -### 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 - - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/templates/docx", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Test DOCX", - documents: [ - { - name: "string", - file: "base64" - } - ] - }) -}); - -const template = await resp.json(); -``` - -```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." + "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 }, - "file": { + "invite_by": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "description": "Set the role name of the previous party that should invite this party via email." }, "fields": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1952,49 +1029,6 @@ const template = await resp.json(); "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": { @@ -2071,6 +1105,15 @@ const template = 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.", @@ -2124,14 +1167,56 @@ const template = await resp.json(); } ], "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 } } } @@ -2141,45 +1226,39 @@ const template = await resp.json(); } ``` -### 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 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/templates/pdf", { +const resp = await fetch("https://api.docuseal.com/submissions/docx", { method: "POST", headers: { "X-Auth-Token": "API_KEY" }, body: JSON.stringify({ - name: "Test PDF", + name: "Test Submission Document", + variables: { + variable_name: "value" + }, documents: [ { name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] }) }); -const template = await resp.json(); +const submitters = await resp.json(); ``` ```json @@ -2190,10 +1269,10 @@ const template = await resp.json(); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -2202,22 +1281,65 @@ const template = await resp.json(); "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_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 + }, + "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": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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", @@ -2236,107 +1358,198 @@ const template = await resp.json(); "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." }, - "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." + "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" }, - "options": { - "type": "array", - "description": "An array of option values for 'select' field type.", - "items": { - "type": "string" - }, - "example": [ - "Option A", - "Option B" - ] + "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", @@ -2374,6 +1587,15 @@ const template = 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.", @@ -2427,24 +1649,51 @@ const template = await resp.json(); } ], "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 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 + "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 } } } @@ -2454,110 +1703,14 @@ const template = await resp.json(); } ``` -### Merge templates +### Create a submission from HTML -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. +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/templates/merge", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - template_ids: [ - 321, - 432 - ], - name: "Merged Template" - }) -}); - -const template = await resp.json(); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } - } - } -} -``` - -### 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 - - -```nodejs -const fetch = require("node-fetch"); - -const resp = await fetch("https://api.docuseal.com/submissions/pdf", { +const resp = await fetch("https://api.docuseal.com/submissions/html", { method: "POST", headers: { "X-Auth-Token": "API_KEY" @@ -2566,22 +1719,16 @@ const resp = await fetch("https://api.docuseal.com/submissions/pdf", { name: "Test Submission Document", documents: [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + name: "Test Document", + html: `

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

+` } ], submitters: [ @@ -2606,8 +1753,8 @@ const submission = await resp.json(); "tags": [ "Submissions" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2622,7 +1769,7 @@ const submission = await resp.json(); "properties": { "name": { "type": "string", - "description": "Name of the document submission.", + "description": "Name of the document submission", "example": "Test Submission Document" }, "send_email": { @@ -2671,209 +1818,142 @@ const submission = await resp.json(); }, "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": [ - "name", - "file" + "html" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" }, - "file": { - "example": "base64", + "html": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "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": "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.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", "required": [ @@ -3009,6 +2089,15 @@ const submission = 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.", @@ -3062,6 +2151,13 @@ const submission = await resp.json(); } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3091,20 +2187,10 @@ const submission = await resp.json(); } } }, - "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 } } } @@ -3114,44 +2200,21 @@ const submission = await resp.json(); } ``` -### Create a submission from HTML +### Archive a submission -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 archive a submission. ```nodejs const fetch = require("node-fetch"); -const resp = await fetch("https://api.docuseal.com/submissions/html", { - method: "POST", +const resp = await fetch("https://api.docuseal.com/submissions/1001", { + method: "DELETE", 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(); +await resp.json(); ``` ```json @@ -3164,210 +2227,339 @@ const submission = await resp.json(); "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 + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +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/submitters", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const { data, pagination } = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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." + } + ] +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submitters/500001", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const submitter = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submitters/500001", { + method: "PUT", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + email: "john.doe@example.com", + fields: [ + { + name: "First Name", + default_value: "Acme" + } + ] + }) +}); + +const submitter = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", - "default": false + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" }, - "order": { + "phone": { "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 phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "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." }, - "bcc_completed": { + "external_id": { "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "send_email": { + "type": "boolean", + "description": "Set `true` to re-send signature request emails." + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to re-send signature request via phone number SMS.", + "default": false }, "reply_to": { "type": "string", "description": "Specify Reply-To address to use in the notification emails." }, - "expire_at": { + "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\" }" + }, + "completed_redirect_url": { "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" + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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." - } + "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 }, - "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." - } + "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}}." } } }, - "submitters": { + "fields": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "email" + "name" ], "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 + "description": "Document template field name.", + "example": "First Name" }, - "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": { + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { "oneOf": [ { "type": "string" @@ -3377,687 +2569,415 @@ const submission = await resp.json(); }, { "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." } + ] + } + } + ], + "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." + }, + "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" } - }, - "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 - } + ], + "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." } } }, - "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 - - -```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": [ - { - "AuthToken": [] - } - ], - "tags": [ + "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" + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### 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": "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", - "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 - } - } - } - } - } - } - } - } - }, - "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 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}} fillable field syntax to define fillable fields, as in a PDF.
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/submissions/docx", { - method: "POST", - headers: { - "X-Auth-Token": "API_KEY" - }, - body: JSON.stringify({ - name: "Test Submission Document", - variables: { - variable_name: "value" + "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." }, - 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", - "example": { - "variable_name": "value" + "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 + } + ] +} +``` + +### 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: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 } - }, - "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": { + ] + } + ] + } + ] + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "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": "Specify BCC address to send signed documents to after the completion." + "description": "Name of the template", + "example": "Test PDF" }, - "reply_to": { + "folder_name": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "The folder's name to which the template should be created." }, - "expire_at": { + "external_id": { "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" + "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" }, - "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." - } + "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", @@ -4076,141 +2996,49 @@ const submitters = await resp.json(); "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 + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", - "description": "A list of configurations for document form fields.", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { "type": "string", - "description": "Document field name.", - "example": "First Name" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -4220,6 +3048,57 @@ const submitters = await resp.json(); "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": { @@ -4296,6 +3175,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.", @@ -4349,44 +3237,865 @@ const submitters = await resp.json(); } ], "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 + + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/docx", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test DOCX", + documents: [ + { + name: "string", + file: "base64" + } + ] + }) +}); + +const template = await resp.json(); +``` + +```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" + } + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### 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 + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/html", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + html: `

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

+`, + name: "Test Template" + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### 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/1000001/clone", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Cloned Template" + }) +}); + +const template = await resp.json(); +``` + +```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. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/merge", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + template_ids: [ + 321, + 432 + ], + name: "Merged Template" + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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/1000001/documents", { + method: "PUT", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + documents: [ + { + file: "string" + } + ] + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4396,3 +4105,47 @@ const submitters = await resp.json(); } ``` +### 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 + } + ] +} +``` + 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,11 +1,11 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->listTemplates(['limit' => 10]); +$docuseal->listSubmissions(['limit' => 10]); ``` ```json @@ -16,47 +16,62 @@ $docuseal->listTemplates(['limit' => 10]); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -65,7 +80,7 @@ $docuseal->listTemplates(['limit' => 10]); "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -74,7 +89,7 @@ $docuseal->listTemplates(['limit' => 10]); "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -83,7 +98,7 @@ $docuseal->listTemplates(['limit' => 10]); "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -92,20 +107,20 @@ $docuseal->listTemplates(['limit' => 10]); "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->getTemplate(1000001); +$docuseal->getSubmission(1001); ``` ```json @@ -116,10 +131,10 @@ $docuseal->getTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -128,21 +143,21 @@ $docuseal->getTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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->archiveTemplate(1000001); +$docuseal->getSubmissionDocuments(1001); ``` ```json @@ -153,10 +168,10 @@ $docuseal->archiveTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -165,23 +180,29 @@ $docuseal->archiveTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->updateTemplate(1000001, [ - 'name' => 'New Document Name', - 'folder_name' => 'New Folder' +$docuseal->createSubmission([ + 'template_id' => 1000001, + 'send_email' => true, + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] + ] ]); ``` @@ -193,277 +214,79 @@ $docuseal->updateTemplate(1000001, [ } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->listSubmissions(['limit' => 10]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->createSubmission([ - 'template_id' => 1000001, - 'send_email' => true, - 'submitters' => [ - [ - 'role' => 'First Party', - 'email' => 'john.doe@example.com' - ] - ] -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,51 +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); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" +$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 + ] + ] + ] + ] + ] ], - "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 - } + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->archiveSubmission(1001); +]); ``` ```json @@ -819,85 +655,8 @@ $docuseal->archiveSubmission(1001); "tags": [ "Submissions" ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -906,227 +665,286 @@ $docuseal->createSubmissionFromEmails([ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->getSubmitter(500001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->updateSubmitter(500001, [ - 'email' => 'john.doe@example.com', - 'fields' => [ - [ - 'name' => 'First Name', - 'default_value' => 'Acme' - ] - ] -]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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." + } }, - "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}}." + "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." + } } } }, - "fields": { + "submitters": { "type": "array", - "description": "A list of configurations for template document form fields.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name" + "email" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "The name of the submitter." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { + "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" @@ -1136,157 +954,232 @@ $docuseal->updateSubmitter(500001, [ }, { "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." } - ] - } - } - ], - "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." - }, - "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" + }, + "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" + } + } } - ], - "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 } } } @@ -1296,130 +1189,28 @@ $docuseal->updateSubmitter(500001, [ } ``` -### List all submitters +### Create a submission from DOCX -The API endpoint provides the ability to retrieve a list of submitters. +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->listSubmitters(['limit' => 10]); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" +$docuseal->createSubmissionFromDocx([ + 'name' => 'Test Submission Document', + 'variables' => [ + 'variable_name' => 'value' ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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->updateTemplateDocuments(1000001, [ 'documents' => [ [ - 'file' => 'string' + 'name' => 'string', + 'file' => 'base64' + ] + ], + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' ] ] ]); @@ -1433,389 +1224,239 @@ $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 - } + "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": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true }, - "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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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" + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." + "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" + } }, - "html_footer": { + "order": { "type": "string", - "description": "HTML template of the footer to be displayed on every page." + "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" + ] }, - "name": { + "completed_redirect_url": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Specify URL to redirect to after the submission completion." }, - "size": { + "bcc_completed": { "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" + "description": "Specify BCC address to send signed documents to after the completion." }, - "external_id": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "folder_name": { + "expire_at": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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 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": { + "name": { "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "description": "Name of the document." }, - "name": { + "file": { + "example": "base64", "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```php -$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); - -$docuseal->createTemplateFromDocx([ - 'name' => 'Test DOCX', - 'documents' => [ - [ - 'name' => 'string', - 'file' => 'base64' - ] - ] -]); -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { + "role": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1825,49 +1466,6 @@ $docuseal->createTemplateFromDocx([ "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": { @@ -1944,6 +1542,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,51 +1604,87 @@ $docuseal->createTemplateFromDocx([ } ], "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" + } } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```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 - ] - ] - ] - ] + }, + "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' ] ] ]); @@ -2055,10 +1698,10 @@ $docuseal->createTemplateFromPdf([ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2067,82 +1710,247 @@ $docuseal->createTemplateFromPdf([ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission", + "example": "Test Submission Document" }, - "folder_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": { "type": "string", - "description": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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": [ - "name", - "file" + "html" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" }, - "file": { - "example": "base64", + "html": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2152,57 +1960,46 @@ $docuseal->createTemplateFromPdf([ "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." - } + "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." } } }, - "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": { @@ -2239,6 +2036,15 @@ $docuseal->createTemplateFromPdf([ ], "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.", @@ -2292,24 +2098,46 @@ $docuseal->createTemplateFromPdf([ } ], "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 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 + "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 } } } @@ -2319,20 +2147,51 @@ $docuseal->createTemplateFromPdf([ } ``` -### Merge templates +### Archive a submission -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. +The API endpoint allows you to archive a submission. ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->mergeTemplates([ - 'template_ids' => [ - 321, - 432 +$docuseal->archiveSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } ], - 'name' => 'Merged Template' -]); + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +The API endpoint provides the ability to retrieve a list of submitters. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->listSubmitters(['limit' => 10]); ``` ```json @@ -2343,103 +2202,151 @@ $docuseal->mergeTemplates([ } ], "tags": [ - "Templates" + "Submitters" ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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 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 +### Get a submitter +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. ```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 - ] - ] - ] - ] - ] +$docuseal->getSubmitter(500001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } ], - 'submitters' => [ + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->updateSubmitter(500001, [ + 'email' => 'john.doe@example.com', + 'fields' => [ [ - 'role' => 'First Party', - 'email' => 'john.doe@example.com' + 'name' => 'First Name', + 'default_value' => 'Acme' ] ] ]); @@ -2453,971 +2360,300 @@ $docuseal->createSubmissionFromPdf([ } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, - "order": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" }, - "reply_to": { + "completed_redirect_url": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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" + "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 }, - "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." + "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}}." + } } }, - "documents": { + "fields": { "type": "array", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name", - "file" + "name" ], "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." + "description": "Document template field name.", + "example": "First 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" - ] - }, - "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." - } + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" } - } - }, - "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 + ], + "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" }, - "send_sms": { + "readonly": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "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." + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." }, - "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." - } + "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" } - }, - "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 - } + ], + "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." } } }, - "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": [ - { - "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": { + "preferences": { "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 - } + "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 } } } @@ -3427,6 +2663,143 @@ and typesetting industry

} ``` +### 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 + } + ] +} +``` + ### 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 @@ -3551,7 +2924,8 @@ $docuseal->createTemplateFromPdf([ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3697,6 +3071,15 @@ $docuseal->createTemplateFromPdf([ ], "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.", @@ -3750,6 +3133,13 @@ $docuseal->createTemplateFromPdf([ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3777,112 +3167,66 @@ $docuseal->createTemplateFromPdf([ } ``` -### Create a submission from DOCX +### 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 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 ```php $docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); -$docuseal->createSubmissionFromDocx([ - 'name' => 'Test Submission Document', - 'variables' => [ - 'variable_name' => 'value' - ], +$docuseal->createTemplateFromDocx([ + 'name' => 'Test DOCX', '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", - "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": { +``` + +```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": "Specify BCC address to send signed documents to after the completion." + "description": "Name of the template", + "example": "Test DOCX" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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", @@ -3898,144 +3242,52 @@ $docuseal->createSubmissionFromDocx([ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "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 + "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", - "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" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -4045,6 +3297,49 @@ $docuseal->createSubmissionFromDocx([ "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": { @@ -4121,6 +3416,15 @@ $docuseal->createSubmissionFromDocx([ ], "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.", @@ -4174,44 +3478,472 @@ $docuseal->createSubmissionFromDocx([ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } } } + } + } + } + } + } + } + } + } + } +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### 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. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->mergeTemplates([ + 'template_ids' => [ + 321, + 432 + ], + 'name' => 'Merged Template' +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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->updateTemplateDocuments(1000001, [ + 'documents' => [ + [ + 'file' => 'string' + ] + ] +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4221,3 +3953,40 @@ $docuseal->createSubmissionFromDocx([ } ``` +### 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 + } + ] +} +``` + 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,6 +1,6 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```python from docuseal import docuseal @@ -19,47 +19,62 @@ docuseal.list_submissions({ "limit": 10 }) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -68,7 +83,7 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -77,7 +92,7 @@ docuseal.list_submissions({ "limit": 10 }) "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -86,7 +101,7 @@ docuseal.list_submissions({ "limit": 10 }) "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -95,15 +110,15 @@ docuseal.list_submissions({ "limit": 10 }) "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```python from docuseal import docuseal @@ -111,7 +126,7 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.get_template(1000001) +docuseal.get_submission(1001) ``` ```json @@ -122,10 +137,10 @@ docuseal.get_template(1000001) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -134,16 +149,16 @@ docuseal.get_template(1000001) "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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 @@ -151,7 +166,7 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.archive_template(1000001) +docuseal.get_submission_documents(1001) ``` ```json @@ -162,10 +177,10 @@ docuseal.archive_template(1000001) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -174,16 +189,16 @@ docuseal.archive_template(1000001) "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```python from docuseal import docuseal @@ -191,9 +206,15 @@ 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" +docuseal.create_submission({ + "template_id": 1000001, + "send_email": True, + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" + } + ] }) ``` @@ -205,283 +226,79 @@ docuseal.update_template(1000001, { } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.list_submissions({ "limit": 10 }) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.create_submission({ - "template_id": 1000001, - "send_email": True, - "submitters": [ - { - "role": "First Party", - "email": "john.doe@example.com" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,47 +629,35 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.get_submission(1001) -``` - -```json -{ - "security": [ +docuseal.create_submission_from_pdf({ + "name": "Test Submission Document", + "documents": [ { - "AuthToken": [] + "name": "string", + "file": "base64", + "fields": [ + { + "name": "string", + "areas": [ + { + "x": 0, + "y": 0, + "w": 0, + "h": 0, + "page": 1 + } + ] + } + ] } ], - "tags": [ - "Submissions" - ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + "submitters": [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + "role": "First Party", + "email": "john.doe@example.com" } ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.archive_submission(1001) +}) ``` ```json @@ -843,91 +670,8 @@ docuseal.archive_submission(1001) "tags": [ "Submissions" ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -936,521 +680,533 @@ docuseal.create_submission_from_emails({ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.get_submitter(500001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.update_submitter(500001, { - "email": "john.doe@example.com", - "fields": [ - { - "name": "First Name", - "default_value": "Acme" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "Name of the document." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" + "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" ] } } - ], - "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 + "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." }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" }, - "validation": { + "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", - "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." - } - } + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." }, - "preferences": { + "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", - "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" + "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." + } } - ], - "default": false - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.list_submissions({ "limit": 10 }) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." + }, + "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 + } + } + } + } } - ] + } } ``` -### Update template documents +### Create a submission from DOCX -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 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 @@ -1458,10 +1214,21 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.update_template_documents(1000001, { +docuseal.create_submission_from_docx({ + "name": "Test Submission Document", + "variables": { + "variable_name": "value" + }, "documents": [ { - "file": "string" + "name": "string", + "file": "base64" + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" } ] }) @@ -1475,183 +1242,10 @@ docuseal.update_template_documents(1000001, { } ], "tags": [ - "Templates" + "Submissions" ], - "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 submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -1660,213 +1254,227 @@ and typesetting industry

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

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

\n" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true }, - "html_footer": { + "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": "HTML template of the footer to be displayed on every page." + "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" + ] }, - "name": { + "completed_redirect_url": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Specify URL to redirect to after the submission completion." }, - "size": { + "bcc_completed": { "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" + "description": "Specify BCC address to send signed documents to after the completion." }, - "external_id": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "folder_name": { + "expire_at": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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 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": { + "name": { "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "description": "Name of the document." }, - "name": { + "file": { + "example": "base64", "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```python -from docuseal import docuseal - -docuseal.key = "API_KEY" -docuseal.url = "https://api.docuseal.com" - -docuseal.create_template_from_docx({ - "name": "Test DOCX", - "documents": [ - { - "name": "string", - "file": "base64" - } - ] -}) -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { + "role": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1876,49 +1484,6 @@ docuseal.create_template_from_docx({ "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": { @@ -1995,6 +1560,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,14 +1622,51 @@ docuseal.create_template_from_docx({ } ], "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 } } } @@ -2065,10 +1676,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 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 @@ -2076,26 +1686,26 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_template_from_pdf({ - "name": "Test PDF", +docuseal.create_submission_from_html({ + "name": "Test Submission Document", "documents": [ { - "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] + "name": "Test Document", + "html": """

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

+""" + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" } ] }) @@ -2109,10 +1719,10 @@ docuseal.create_template_from_pdf({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2121,141 +1731,295 @@ docuseal.create_template_from_pdf({ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission", + "example": "Test Submission Document" }, - "folder_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": { "type": "string", - "description": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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": [ - "name", - "file" + "html" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" }, - "file": { - "example": "base64", + "html": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "HTML document content with field tags.", + "example": "

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

\n" }, - "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" - ] + "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", @@ -2293,6 +2057,15 @@ docuseal.create_template_from_pdf({ ], "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.", @@ -2346,50 +2119,66 @@ docuseal.create_template_from_pdf({ } ], "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 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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. - + }, + "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 + } + } + } + } + } + } +} +``` + +### Archive a submission + +The API endpoint allows you to archive a submission. + ```python from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.merge_templates({ - "template_ids": [ - 321, - 432 - ], - "name": "Merged Template" -}) +docuseal.archive_submission(1001) ``` ```json @@ -2400,73 +2189,28 @@ docuseal.merge_templates({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 } - } + ] } ``` -### 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 +### List all submitters +The API endpoint provides the ability to retrieve a list of submitters. ```python from docuseal import docuseal @@ -2474,35 +2218,123 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_submission_from_pdf({ - "name": "Test Submission Document", - "documents": [ +docuseal.list_submissions({ "limit": 10 }) +``` + +```json +{ + "security": [ { - "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] + "AuthToken": [] } ], - "submitters": [ + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "parameters": [ { - "role": "First Party", - "email": "john.doe@example.com" + "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", + "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." } ] -}) +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.get_submitter(500001) ``` ```json @@ -2513,507 +2345,348 @@ docuseal.create_submission_from_pdf({ } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.update_submitter(500001, { + "email": "john.doe@example.com", + "fields": [ + { + "name": "First Name", + "default_value": "Acme" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ], + "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, - "order": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" }, - "reply_to": { + "completed_redirect_url": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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" + "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 }, - "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." + "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}}." + } } }, - "documents": { + "fields": { "type": "array", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name", - "file" + "name" ], "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." + "description": "Document template field name.", + "example": "First 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" - ] - }, - "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" + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } ] } } - } - }, - "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 + ], + "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" }, - "send_sms": { + "readonly": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "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": { + "required": { "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 + "description": "Set `true` to make the field required." }, - "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." - } + "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" } - }, - "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 - } + ], + "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." } } }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" + "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" + } + } } } } } - }, - "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 } } } @@ -3023,9 +2696,9 @@ docuseal.create_submission_from_pdf({ } ``` -### Create a submission from HTML +### List all templates -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 provides the ability to retrieve a list of available document templates. ```python from docuseal import docuseal @@ -3033,29 +2706,7 @@ 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" - } - ] -}) +docuseal.list_submissions({ "limit": 10 }) ``` ```json @@ -3066,250 +2717,266 @@ and typesetting industry

} ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], + "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 + } + ] +} +``` + +### 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 + } + ] + } + ] + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "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 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." + "description": "Name of the template", + "example": "Test PDF" }, - "reply_to": { + "folder_name": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "The folder's name to which the template should be created." }, - "expire_at": { + "external_id": { "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" + "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" }, - "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." - } + "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 submission with multiple documents.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "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." + "description": "Name of the document." }, - "html_footer": { + "file": { + "example": "base64", "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 + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", - "description": "A list of configurations for document form fields.", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { "type": "string", - "description": "Document field name.", - "example": "First Name" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3319,6 +2986,57 @@ and typesetting industry

"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": { @@ -3395,6 +3113,15 @@ and typesetting industry

], "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.", @@ -3448,39 +3175,31 @@ and typesetting industry

} ], "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": { + "flatten": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", + "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 } } } @@ -3490,9 +3209,9 @@ and typesetting industry

} ``` -### Create a template from PDF +### Create a template from Word DOCX -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 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 ```python @@ -3501,26 +3220,12 @@ from docuseal import docuseal docuseal.key = "API_KEY" docuseal.url = "https://api.docuseal.com" -docuseal.create_template_from_pdf({ - "name": "Test PDF", +docuseal.create_template_from_docx({ + "name": "Test DOCX", "documents": [ { "name": "string", - "file": "base64", - "fields": [ - { - "name": "string", - "areas": [ - { - "x": 0, - "y": 0, - "w": 0, - "h": 0, - "page": 1 - } - ] - } - ] + "file": "base64" } ] }) @@ -3536,8 +3241,8 @@ docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3552,17 +3257,17 @@ docuseal.create_template_from_pdf({ "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." + "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 PDF.", + "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.", @@ -3582,14 +3287,14 @@ docuseal.create_template_from_pdf({ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the DOCX file or downloadable file URL" }, "fields": { - "type": "array", "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", "items": { "type": "object", "properties": { @@ -3617,7 +3322,8 @@ docuseal.create_template_from_pdf({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3640,13 +3346,6 @@ docuseal.create_template_from_pdf({ "type": "array", "items": { "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], "properties": { "x": { "type": "number", @@ -3666,8 +3365,7 @@ docuseal.create_template_from_pdf({ }, "page": { "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 + "description": "Page number of the field area. Starts from 1." }, "option": { "type": "string", @@ -3763,6 +3461,15 @@ docuseal.create_template_from_pdf({ ], "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.", @@ -3816,6 +3523,13 @@ docuseal.create_template_from_pdf({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3824,16 +3538,6 @@ docuseal.create_template_from_pdf({ } } } - }, - "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 } } } @@ -3843,9 +3547,9 @@ docuseal.create_template_from_pdf({ } ``` -### Create a submission from DOCX +### Create a template from HTML -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 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 @@ -3853,23 +3557,17 @@ 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.create_template_from_html({ + "html": """

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

+""", + "name": "Test Template" }) ``` @@ -3881,10 +3579,10 @@ docuseal.create_submission_from_docx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -3893,394 +3591,419 @@ docuseal.create_submission_from_docx({ "schema": { "type": "object", "required": [ - "documents", - "submitters" + "html" ], "properties": { - "name": { + "html": { "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 + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." }, - "order": { + "html_footer": { "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": "HTML template of the footer to be displayed on every page." }, - "completed_redirect_url": { + "name": { "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, - "bcc_completed": { + "size": { "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "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" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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": { - "name": { + "html": { "type": "string", - "description": "Name of the document." + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "file": { - "example": "base64", + "name": { "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." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } - }, - "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 - } - } - } - } - } + } + } + } + } + } + } +} +``` + +### 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. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.merge_templates({ + "template_ids": [ + 321, + 432 + ], + "name": "Merged Template" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.update_template_documents(1000001, { + "documents": [ + { + "file": "string" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4290,3 +4013,43 @@ docuseal.create_submission_from_docx({ } ``` +### 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 + } + ] +} +``` + 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,6 +1,6 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```ruby require "docuseal" @@ -8,7 +8,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.list_templates(limit: 10) +Docuseal.list_submissions(limit: 10) ``` ```json @@ -19,47 +19,62 @@ Docuseal.list_templates(limit: 10) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -68,7 +83,7 @@ Docuseal.list_templates(limit: 10) "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -77,7 +92,7 @@ Docuseal.list_templates(limit: 10) "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -86,7 +101,7 @@ Docuseal.list_templates(limit: 10) "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -95,15 +110,15 @@ Docuseal.list_templates(limit: 10) "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```ruby require "docuseal" @@ -111,7 +126,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.get_template(1000001) +Docuseal.get_submission(1001) ``` ```json @@ -122,10 +137,10 @@ Docuseal.get_template(1000001) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -134,16 +149,16 @@ Docuseal.get_template(1000001) "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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" @@ -151,7 +166,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.archive_template(1000001) +Docuseal.get_submission_documents(1001) ``` ```json @@ -162,10 +177,10 @@ Docuseal.archive_template(1000001) } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -174,16 +189,16 @@ Docuseal.archive_template(1000001) "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```ruby require "docuseal" @@ -191,9 +206,15 @@ 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" +Docuseal.create_submission({ + template_id: 1000001, + send_email: true, + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] }) ``` @@ -205,283 +226,79 @@ Docuseal.update_template(1000001, { } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.list_submissions(limit: 10) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.create_submission({ - template_id: 1000001, - send_email: true, - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,47 +629,35 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.get_submission(1001) -``` - -```json -{ - "security": [ +Docuseal.create_submission_from_pdf({ + name: "Test Submission Document", + documents: [ { - "AuthToken": [] + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ], - "tags": [ - "Submissions" - ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + submitters: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + role: "First Party", + email: "john.doe@example.com" } ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.archive_submission(1001) +}) ``` ```json @@ -843,91 +670,8 @@ Docuseal.archive_submission(1001) "tags": [ "Submissions" ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -936,521 +680,533 @@ Docuseal.create_submission_from_emails({ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.get_submitter(500001) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.update_submitter(500001, { - email: "john.doe@example.com", - fields: [ - { - name: "First Name", - default_value: "Acme" - } - ] -}) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "Name of the document." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" + "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" ] } } - ], - "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 + "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." }, - "required": { - "type": "boolean", - "description": "Set `true` to make the field required." + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" }, - "validation": { + "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", - "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." - } - } + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." }, - "preferences": { + "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", - "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" + "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." + } } - ], - "default": false - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.list_submitters(limit: 10) -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." + }, + "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 + } + } + } + } } - ] + } } ``` -### Update template documents +### Create a submission from DOCX -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 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" @@ -1458,10 +1214,21 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.update_template_documents(1000001, { +Docuseal.create_submission_from_docx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, documents: [ { - file: "string" + name: "string", + file: "base64" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] }) @@ -1475,183 +1242,10 @@ Docuseal.update_template_documents(1000001, { } ], "tags": [ - "Templates" + "Submissions" ], - "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 submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -1660,213 +1254,227 @@ and typesetting industry

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

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

\n" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true }, - "html_footer": { + "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": "HTML template of the footer to be displayed on every page." + "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" + ] }, - "name": { + "completed_redirect_url": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Specify URL to redirect to after the submission completion." }, - "size": { + "bcc_completed": { "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" + "description": "Specify BCC address to send signed documents to after the completion." }, - "external_id": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "folder_name": { + "expire_at": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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 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": { + "name": { "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "description": "Name of the document." }, - "name": { + "file": { + "example": "base64", "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```ruby -require "docuseal" - -Docuseal.key = ENV["DOCUSEAL_API_KEY"] -Docuseal.url = "https://api.docuseal.com" - -Docuseal.create_template_from_docx({ - name: "Test DOCX", - documents: [ - { - name: "string", - file: "base64" - } - ] -}) -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { + "role": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1876,49 +1484,6 @@ Docuseal.create_template_from_docx({ "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": { @@ -1995,6 +1560,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,14 +1622,51 @@ Docuseal.create_template_from_docx({ } ], "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 } } } @@ -2065,10 +1676,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 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" @@ -2076,26 +1686,26 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_template_from_pdf({ - name: "Test PDF", +Docuseal.create_submission_from_html({ + name: "Test Submission Document", documents: [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + name: "Test Document", + html: "

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

+" + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] }) @@ -2109,10 +1719,10 @@ Docuseal.create_template_from_pdf({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2121,141 +1731,295 @@ Docuseal.create_template_from_pdf({ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission", + "example": "Test Submission Document" }, - "folder_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": { "type": "string", - "description": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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": [ - "name", - "file" + "html" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" }, - "file": { - "example": "base64", + "html": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "HTML document content with field tags.", + "example": "

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

\n" }, - "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" - ] + "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", @@ -2293,6 +2057,15 @@ Docuseal.create_template_from_pdf({ ], "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.", @@ -2346,36 +2119,58 @@ Docuseal.create_template_from_pdf({ } ], "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 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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. + }, + "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 + } + } + } + } + } + } +} +``` + +### Archive a submission + +The API endpoint allows you to archive a submission. ```ruby require "docuseal" @@ -2383,13 +2178,7 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.merge_templates({ - template_ids: [ - 321, - 432 - ], - name: "Merged Template" -}) +Docuseal.archive_submission(1001) ``` ```json @@ -2400,73 +2189,28 @@ Docuseal.merge_templates({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 } - } + ] } ``` -### 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 +### List all submitters +The API endpoint provides the ability to retrieve a list of submitters. ```ruby require "docuseal" @@ -2474,35 +2218,123 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_submission_from_pdf({ - name: "Test Submission Document", - documents: [ +Docuseal.list_submitters(limit: 10) +``` + +```json +{ + "security": [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + "AuthToken": [] } ], - submitters: [ + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "parameters": [ { - role: "First Party", - email: "john.doe@example.com" + "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", + "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." } ] -}) +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.get_submitter(500001) ``` ```json @@ -2513,507 +2345,348 @@ Docuseal.create_submission_from_pdf({ } ], "tags": [ - "Submissions" + "Submitters" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", - "parameters": [], - "requestBody": { + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.update_submitter(500001, { + email: "john.doe@example.com", + fields: [ + { + name: "First Name", + default_value: "Acme" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ], + "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, - "order": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" }, - "reply_to": { + "completed_redirect_url": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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" + "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 }, - "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." + "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}}." + } } }, - "documents": { + "fields": { "type": "array", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name", - "file" + "name" ], "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." + "description": "Document template field name.", + "example": "First 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" - ] - }, - "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" + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } ] } } - } - }, - "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 + ], + "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" }, - "send_sms": { + "readonly": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "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": { + "required": { "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 + "description": "Set `true` to make the field required." }, - "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." - } + "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" } - }, - "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 - } + ], + "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." } } }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" + "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" + } + } } } } } - }, - "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 } } } @@ -3023,9 +2696,9 @@ Docuseal.create_submission_from_pdf({ } ``` -### Create a submission from HTML +### List all templates -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 provides the ability to retrieve a list of available document templates. ```ruby require "docuseal" @@ -3033,29 +2706,7 @@ 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" - } - ] -}) +Docuseal.list_templates(limit: 10) ``` ```json @@ -3066,250 +2717,266 @@ and typesetting industry

} ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from HTML", - "operationId": "createSubmissionFromHtml", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "documents", - "submitters" - ], + "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 + } + ] +} +``` + +### 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 + } + ] + } + ] + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "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 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." + "description": "Name of the template", + "example": "Test PDF" }, - "reply_to": { + "folder_name": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "The folder's name to which the template should be created." }, - "expire_at": { + "external_id": { "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" + "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" }, - "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." - } + "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 submission with multiple documents.", "items": { "type": "object", "required": [ - "html" + "name", + "file" ], "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." + "description": "Name of the document." }, - "html_footer": { + "file": { + "example": "base64", "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 + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", - "description": "A list of configurations for document form fields.", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { "type": "string", - "description": "Document field name.", - "example": "First Name" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3319,6 +2986,57 @@ and typesetting industry

"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": { @@ -3395,6 +3113,15 @@ and typesetting industry

], "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.", @@ -3448,39 +3175,31 @@ and typesetting industry

} ], "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": { + "flatten": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", + "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 } } } @@ -3490,9 +3209,9 @@ and typesetting industry

} ``` -### Create a template from PDF +### Create a template from Word DOCX -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 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 ```ruby @@ -3501,26 +3220,12 @@ require "docuseal" Docuseal.key = ENV["DOCUSEAL_API_KEY"] Docuseal.url = "https://api.docuseal.com" -Docuseal.create_template_from_pdf({ - name: "Test PDF", +Docuseal.create_template_from_docx({ + name: "Test DOCX", documents: [ { name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "base64" } ] }) @@ -3536,8 +3241,8 @@ Docuseal.create_template_from_pdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3552,17 +3257,17 @@ Docuseal.create_template_from_pdf({ "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." + "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 PDF.", + "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.", @@ -3582,14 +3287,14 @@ Docuseal.create_template_from_pdf({ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the DOCX file or downloadable file URL" }, "fields": { - "type": "array", "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", "items": { "type": "object", "properties": { @@ -3617,7 +3322,8 @@ Docuseal.create_template_from_pdf({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3640,13 +3346,6 @@ Docuseal.create_template_from_pdf({ "type": "array", "items": { "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], "properties": { "x": { "type": "number", @@ -3666,8 +3365,7 @@ Docuseal.create_template_from_pdf({ }, "page": { "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 + "description": "Page number of the field area. Starts from 1." }, "option": { "type": "string", @@ -3763,6 +3461,15 @@ Docuseal.create_template_from_pdf({ ], "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.", @@ -3816,6 +3523,13 @@ Docuseal.create_template_from_pdf({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3824,16 +3538,6 @@ Docuseal.create_template_from_pdf({ } } } - }, - "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 } } } @@ -3843,9 +3547,9 @@ Docuseal.create_template_from_pdf({ } ``` -### Create a submission from DOCX +### Create a template from HTML -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 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" @@ -3853,23 +3557,17 @@ 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.create_template_from_html({ + html: "

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

+", + name: "Test Template" }) ``` @@ -3881,10 +3579,10 @@ Docuseal.create_submission_from_docx({ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -3893,394 +3591,419 @@ Docuseal.create_submission_from_docx({ "schema": { "type": "object", "required": [ - "documents", - "submitters" + "html" ], "properties": { - "name": { + "html": { "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 + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." }, - "order": { + "html_footer": { "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": "HTML template of the footer to be displayed on every page." }, - "completed_redirect_url": { + "name": { "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, - "bcc_completed": { + "size": { "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "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" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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": { - "name": { + "html": { "type": "string", - "description": "Name of the document." + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "file": { - "example": "base64", + "name": { "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." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } - }, - "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 - } - } - } - } - } + } + } + } + } + } + } +} +``` + +### 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. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.merge_templates({ + template_ids: [ + 321, + 432 + ], + name: "Merged Template" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.update_template_documents(1000001, { + documents: [ + { + file: "string" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4290,3 +4013,43 @@ Docuseal.create_submission_from_docx({ } ``` +### 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 + } + ] +} +``` + 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,10 +1,10 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```shell curl --request GET \ - --url https://api.docuseal.com/templates \ + --url https://api.docuseal.com/submissions \ --header 'X-Auth-Token: API_KEY' ``` @@ -16,47 +16,62 @@ curl --request GET \ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -65,7 +80,7 @@ curl --request GET \ "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -74,7 +89,7 @@ curl --request GET \ "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -83,7 +98,7 @@ curl --request GET \ "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -92,19 +107,19 @@ curl --request GET \ "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +The API endpoint provides the functionality to retrieve information about a submission. ```shell curl --request GET \ - --url https://api.docuseal.com/templates/1000001 \ + --url https://api.docuseal.com/submissions/1001 \ --header 'X-Auth-Token: API_KEY' ``` @@ -116,10 +131,10 @@ curl --request GET \ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -128,20 +143,20 @@ curl --request GET \ "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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 DELETE \ - --url https://api.docuseal.com/templates/1000001 \ +curl --request GET \ + --url https://api.docuseal.com/submissions/1001/documents \ --header 'X-Auth-Token: API_KEY' ``` @@ -153,10 +168,10 @@ curl --request DELETE \ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -165,23 +180,23 @@ curl --request DELETE \ "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```shell -curl --request PUT \ - --url https://api.docuseal.com/templates/1000001 \ +curl --request POST \ + --url https://api.docuseal.com/submissions \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ - --data '{"name":"New Document Name","folder_name":"New Folder"}' + --data '{"template_id":1000001,"send_email":true,"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' ``` ```json @@ -192,270 +207,79 @@ curl --request PUT \ } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```shell -curl --request GET \ - --url https://api.docuseal.com/submissions \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```shell -curl --request POST \ - --url https://api.docuseal.com/submissions \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"template_id":1000001,"send_email":true,"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,88 +599,17 @@ curl --request POST \ } ``` -### 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 - } - ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```shell -curl --request DELETE \ - --url https://api.docuseal.com/submissions/1001 \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 - } - ] -} -``` +### Create a submission from PDF -### Get submission documents +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 -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' +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 @@ -848,47 +622,8 @@ curl --request GET \ "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -897,891 +632,324 @@ curl --request POST \ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```shell -curl --request GET \ - --url https://api.docuseal.com/submitters/500001 \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```shell -curl --request PUT \ - --url https://api.docuseal.com/submitters/500001 \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"email":"john.doe@example.com","fields":[{"name":"First Name","default_value":"Acme"}]}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." - }, - "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 + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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}}." - } + "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." } }, - "fields": { + "documents": { "type": "array", - "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name" + "name", + "file" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "Name of the document." }, - "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." - }, - "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 - } - } - } - } - } - } - } - } - } - } - } -} -``` - -### List all submitters - -The API endpoint provides the ability to retrieve a list of submitters. - -```shell -curl --request GET \ - --url https://api.docuseal.com/submitters \ - --header 'X-Auth-Token: API_KEY' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```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"}]}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "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. - -```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." - } - } - } - } - } - } -} -``` - -### 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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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": "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." - }, - "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": [ - "html" - ], - "properties": { - "html": { + "file": { + "example": "base64", "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, - "name": { - "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```shell -curl --request POST \ - --url https://api.docuseal.com/templates/docx \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"name":"Test DOCX","documents":[{"name":"string","file":"base64"}]}' -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "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." }, - "file": { + "completed_redirect_url": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1791,49 +959,6 @@ curl --request POST \ "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": { @@ -1910,6 +1035,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,14 +1097,56 @@ curl --request POST \ } ], "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 } } } @@ -1980,17 +1156,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 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/templates/pdf \ + --url https://api.docuseal.com/submissions/docx \ --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":"Test Submission Document","variables":{"variable_name":"value"},"documents":[{"name":"string","file":"base64"}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' ``` ```json @@ -2001,10 +1176,10 @@ curl --request POST \ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from DOCX", + "operationId": "createSubmissionFromDocx", "parameters": [], "requestBody": { "required": true, @@ -2013,22 +1188,65 @@ curl --request POST \ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_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 + }, + "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": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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", @@ -2047,48 +1265,150 @@ curl --request POST \ "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." + }, + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2098,57 +1418,46 @@ curl --request POST \ "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." - } + "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." } } }, - "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": { @@ -2175,15 +1484,24 @@ curl --request POST \ "Courier" ] }, - "color": { + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "background": { "type": "string", - "description": "Font color of the field value.", + "description": "Field box background color.", "enum": [ "black", "white", "blue" - ], - "default": "black" + ] }, "align": { "type": "string", @@ -2238,107 +1556,51 @@ curl --request POST \ } ], "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 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 + "roles": { + "type": "array", + "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", + "items": { + "type": "string" + } } } } - } - } - } - } - } - } -} -``` - -### Merge templates - -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. - -```shell -curl --request POST \ - --url https://api.docuseal.com/templates/merge \ - --header 'X-Auth-Token: API_KEY' \ - --header 'content-type: application/json' \ - --data '{"template_ids":[321,432],"name":"Merged Template"}' -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Templates" - ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." + "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}}." + } + } }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false }, - "shared_link": { + "remove_tags": { "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.", + "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] } } } @@ -2348,17 +1610,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 +### 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/pdf \ + --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":"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"}]}' + --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 @@ -2371,8 +1632,8 @@ curl --request POST \ "tags": [ "Submissions" ], - "summary": "Create a submission from PDF", - "operationId": "createSubmissionFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2387,7 +1648,7 @@ curl --request POST \ "properties": { "name": { "type": "string", - "description": "Name of the document submission.", + "description": "Name of the document submission", "example": "Test Submission Document" }, "send_email": { @@ -2429,132 +1690,56 @@ curl --request POST \ "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" - ] - } - } - } + "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", @@ -2636,6 +1821,15 @@ 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 + }, + "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.", @@ -2774,6 +1968,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.", @@ -2827,6 +2030,13 @@ curl --request POST \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -2856,39 +2066,216 @@ curl --request POST \ } } }, - "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 } } } } } - } + } +} +``` + +### Archive a submission + +The API endpoint allows you to archive a submission. + +```shell +curl --request DELETE \ + --url https://api.docuseal.com/submissions/1001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +The API endpoint provides the ability to retrieve a list of submitters. + +```shell +curl --request GET \ + --url https://api.docuseal.com/submitters \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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." + } + ] +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```shell +curl --request GET \ + --url https://api.docuseal.com/submitters/500001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] } ``` -### Create a submission from HTML +### Update a submitter -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 update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API ```shell -curl --request POST \ - --url https://api.docuseal.com/submissions/html \ +curl --request PUT \ + --url https://api.docuseal.com/submitters/500001 \ --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"}]}' + --data '{"email":"john.doe@example.com","fields":[{"name":"First Name","default_value":"Acme"}]}' ``` ```json @@ -2899,212 +2286,124 @@ curl --request POST \ } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number 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": { + "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\" }" + }, + "completed_redirect_url": { "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" + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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." - } + "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 }, - "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." - } + "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}}." } } }, - "submitters": { + "fields": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "email" + "name" ], "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 + "description": "Document template field name.", + "example": "First Name" }, - "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": { + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { "oneOf": [ { "type": "string" @@ -3114,206 +2413,173 @@ curl --request POST \ }, { "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." } + ] + } + } + ], + "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." + }, + "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" } - }, - "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 - } + ], + "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 } } } @@ -3323,6 +2589,143 @@ curl --request POST \ } ``` +### 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 + } + ] +} +``` + ### 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 @@ -3427,7 +2830,8 @@ curl --request POST \ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3573,6 +2977,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.", @@ -3626,6 +3039,13 @@ curl --request POST \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3653,16 +3073,17 @@ curl --request POST \ } ``` -### Create a submission from DOCX +### 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 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 ```shell curl --request POST \ - --url https://api.docuseal.com/submissions/docx \ + --url https://api.docuseal.com/templates/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"}]}' + --data '{"name":"Test DOCX","documents":[{"name":"string","file":"base64"}]}' ``` ```json @@ -3673,10 +3094,10 @@ curl --request POST \ } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3685,65 +3106,27 @@ curl --request POST \ "schema": { "type": "object", "required": [ - "documents", - "submitters" + "documents" ], "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." + "description": "Name of the template", + "example": "Test DOCX" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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", @@ -3759,144 +3142,52 @@ curl --request POST \ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "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 + "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", - "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" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3906,6 +3197,49 @@ curl --request POST \ "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": { @@ -3982,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.", @@ -4035,44 +3378,454 @@ curl --request POST \ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } } } + } + } + } + } + } + } + } + } + } +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "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": "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." + }, + "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": [ + "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": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + } + } + } + } + } + } + } + } + } +} +``` + +### 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. + +```shell +curl --request POST \ + --url https://api.docuseal.com/templates/merge \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"template_ids":[321,432],"name":"Merged Template"}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { + "type": "array", + "description": "An array of template ids to merge into a new template.", + "items": { + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```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"}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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,13 +1,13 @@ -### List all templates +### List all submissions -The API endpoint provides the ability to retrieve a list of available document templates. +The API endpoint provides the ability to retrieve a list of available submissions. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); ``` ```json @@ -18,47 +18,62 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "List all templates", - "operationId": "getTemplates", + "summary": "List all submissions", + "operationId": "getSubmissions", "parameters": [ { - "name": "q", + "name": "template_id", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer" }, - "description": "Filter templates based on the name partial match." + "description": "The template ID allows you to receive only the submissions created from that specific template." }, { - "name": "slug", + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "completed", + "declined", + "expired" + ] + }, + "description": "Filter submissions by status." + }, + { + "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by unique slug.", - "example": "opaKWh8WWTAcVG" + "description": "Filter submissions based on submitters name, email or phone partial match." }, { - "name": "external_id", + "name": "slug", "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." + "description": "Filter submissions by unique slug.", + "example": "NtLDQM7eJX2ZMd" }, { - "name": "folder", + "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, - "description": "Filter templates by folder name." + "description": "Filter submissions by template folder name." }, { "name": "archived", @@ -67,7 +82,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "schema": { "type": "boolean" }, - "description": "Get only archived templates instead of active ones." + "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", @@ -76,7 +91,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "schema": { "type": "integer" }, - "description": "The number of templates to return. Default value is 10. Maximum value is 100." + "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", @@ -85,7 +100,7 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "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." + "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", @@ -94,22 +109,22 @@ const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); "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." + "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ] } ``` -### Get a template +### Get a submission -The API endpoint provides the functionality to retrieve information about a document template. +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 template = await docuseal.getTemplate(1000001); +const submission = await docuseal.getSubmission(1001); ``` ```json @@ -120,10 +135,10 @@ const template = await docuseal.getTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Get a template", - "operationId": "getTemplate", + "summary": "Get a submission", + "operationId": "getSubmission", "parameters": [ { "name": "id", @@ -132,23 +147,23 @@ const template = await docuseal.getTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Archive a template +### Get submission documents -The API endpoint allows you to archive a document template. +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" }); -await docuseal.archiveTemplate(1000001); +const submission = await docuseal.getSubmissionDocuments(1001); ``` ```json @@ -159,10 +174,10 @@ await docuseal.archiveTemplate(1000001); } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Archive a template", - "operationId": "archiveTemplate", + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", @@ -171,25 +186,31 @@ await docuseal.archiveTemplate(1000001); "schema": { "type": "integer" }, - "description": "The unique identifier of the document template.", - "example": 1000001 + "description": "The unique identifier of the submission.", + "example": 1001 } ] } ``` -### Update a template +### Create a submission -The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. +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 ```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" +const submission = await docuseal.createSubmission({ + template_id: 1000001, + send_email: true, + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] }); ``` @@ -201,281 +222,79 @@ const template = await docuseal.updateTemplate(1000001, { } ], "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 - } + "Submissions" ], + "summary": "Create a submission", + "operationId": "createSubmission", + "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", + "required": [ + "template_id", + "submitters" + ], "properties": { - "name": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", + "example": 1000001 + }, + "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": "The name of the template", - "example": "New Document Name" + "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" + ] }, - "folder_name": { + "completed_redirect_url": { "type": "string", - "description": "The folder's name to which the template should be moved.", - "example": "New Folder" + "description": "Specify URL to redirect to after the submission completion." }, - "roles": { + "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" + }, + "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}}." + } + } + }, + "submitters": { "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. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const { data, pagination } = await docuseal.listSubmissions({ limit: 10 }); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "List all submissions", - "operationId": "getSubmissions", - "parameters": [ - { - "name": "template_id", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The template ID allows you to receive only the submissions created from that specific template." - }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "completed", - "declined", - "expired" - ] - }, - "description": "Filter submissions by status." - }, - { - "name": "q", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions based on submitters name, email or phone partial match." - }, - { - "name": "slug", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by unique slug.", - "example": "NtLDQM7eJX2ZMd" - }, - { - "name": "template_folder", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Filter submissions by template folder name." - }, - { - "name": "archived", - "in": "query", - "required": false, - "schema": { - "type": "boolean" - }, - "description": "Returns only archived submissions when `true` and only active submissions when `false`." - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The number of submissions 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 submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." - }, - { - "name": "before", - "in": "query", - "required": false, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." - } - ] -} -``` - -### 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 - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submission = await docuseal.createSubmission({ - template_id: 1000001, - send_email: true, - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submissions" - ], - "summary": "Create a submission", - "operationId": "createSubmission", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_id", - "submitters" - ], - "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", - "example": 1000001 - }, - "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" - }, - "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}}." - } - } - }, - "submitters": { - "type": "array", - "description": "The list of submitters for the submission.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ @@ -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,55 +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); -``` - -```json -{ - "security": [ +const submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ { - "AuthToken": [] + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] } ], - "tags": [ - "Submissions" - ], - "summary": "Get a submission", - "operationId": "getSubmission", - "parameters": [ + submitters: [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submission.", - "example": 1001 + role: "First Party", + email: "john.doe@example.com" } ] -} -``` - -### Archive a submission - -The API endpoint allows you to archive a submission. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -await docuseal.archiveSubmission(1001); +}); ``` ```json @@ -835,89 +665,8 @@ await docuseal.archiveSubmission(1001); "tags": [ "Submissions" ], - "summary": "Archive a submission", - "operationId": "archiveSubmission", - "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 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", + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", "parameters": [], "requestBody": { "required": true, @@ -926,231 +675,286 @@ const submission = await docuseal.createSubmissionFromEmails({ "schema": { "type": "object", "required": [ - "template_id", - "emails" + "documents", + "submitters" ], "properties": { - "template_id": { - "type": "integer", - "description": "The unique identifier of the template.", - "example": 1000001 - }, - "emails": { + "name": { "type": "string", - "description": "A comma-separated list of email addresses to send the submission to.", - "example": "{{emails}}" + "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 }, - "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. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submitter = await docuseal.getSubmitter(500001); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Get a submitter", - "operationId": "getSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ] -} -``` - -### Update a submitter - -The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const submitter = await docuseal.updateSubmitter(500001, { - email: "john.doe@example.com", - fields: [ - { - name: "First Name", - default_value: "Acme" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] - } - ], - "tags": [ - "Submitters" - ], - "summary": "Update a submitter", - "operationId": "updateSubmitter", - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - }, - "description": "The unique identifier of the submitter.", - "example": 500001 - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the submitter." + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "email": { + "order": { "type": "string", - "description": "The email address of the submitter.", - "format": "email", - "example": "john.doe@example.com" + "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" + ] }, - "phone": { + "completed_redirect_url": { "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." + "description": "Specify URL to redirect to after the submission completion." }, - "external_id": { + "bcc_completed": { "type": "string", - "description": "Your application-specific unique string key to identify this submitter within your app." - }, - "send_email": { - "type": "boolean", - "description": "Set `true` to re-send signature request emails." - }, - "send_sms": { - "type": "boolean", - "description": "Set `true` to re-send signature request via phone number SMS.", - "default": false + "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." }, - "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\" }" - }, - "completed_redirect_url": { + "expire_at": { "type": "string", - "description": "Submitter specific URL to redirect to after the submission completion." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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." + } }, - "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}}." + "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." + } } } }, - "fields": { + "submitters": { "type": "array", - "description": "A list of configurations for template document form fields.", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name" + "email" ], "properties": { "name": { "type": "string", - "description": "Document template field name.", - "example": "First Name" + "description": "The name of the submitter." }, - "default_value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { + "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" @@ -1160,157 +964,232 @@ const submitter = await docuseal.updateSubmitter(500001, { }, { "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." } - ] - } - } - ], - "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." - }, - "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" + }, + "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" + } + } } - ], - "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 } } } @@ -1320,134 +1199,30 @@ const submitter = await docuseal.updateSubmitter(500001, { } ``` -### List all submitters +### Create a submission from DOCX -The API endpoint provides the ability to retrieve a list of submitters. +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 { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); -``` - -```json -{ - "security": [ +const submission = await docuseal.createSubmissionFromDocx({ + name: "Test Submission Document", + variables: { + variable_name: "value" + }, + documents: [ { - "AuthToken": [] + name: "string", + file: "base64" } ], - "tags": [ - "Submitters" - ], - "summary": "List all submitters", - "operationId": "getSubmitters", - "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", - "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." - } - ] -} -``` - -### 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. - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.updateTemplateDocuments(1000001, { - documents: [ + submitters: [ { - file: "string" + role: "First Party", + email: "john.doe@example.com" } ] }); @@ -1461,395 +1236,239 @@ 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 - } + "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": "Template name. Existing name with (Clone) suffix will be used if not specified.", - "example": "Cloned Template" + "description": "Name of the document submission.", + "example": "Test Submission Document" }, - "folder_name": { - "type": "string", - "description": "The folder's name to which the template should be cloned." + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true }, - "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", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "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" + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false }, - "html_header": { - "type": "string", - "description": "HTML template of the header to be displayed on every page." + "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" + } }, - "html_footer": { + "order": { "type": "string", - "description": "HTML template of the footer to be displayed on every page." + "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" + ] }, - "name": { + "completed_redirect_url": { "type": "string", - "description": "Template name. Random uuid will be assigned when not specified.", - "example": "Test Template" + "description": "Specify URL to redirect to after the submission completion." }, - "size": { + "bcc_completed": { "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" + "description": "Specify BCC address to send signed documents to after the completion." }, - "external_id": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "folder_name": { + "expire_at": { "type": "string", - "description": "The folder's name to which the template should be created." + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" }, - "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 + "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 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": { + "name": { "type": "string", - "description": "HTML template with field tags.", - "example": "

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

\n" + "description": "Name of the document." }, - "name": { + "file": { + "example": "base64", "type": "string", - "description": "Document name. Random uuid will be assigned when not specified.", - "example": "Test Document" + "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." } } } - } - } - } - } - } - } -} -``` - -### 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 - - -```typescript -import docuseal from "@docuseal/api"; - -docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); - -const template = await docuseal.createTemplateFromDocx({ - name: "Test DOCX", - documents: [ - { - name: "string", - file: "base64" - } - ] -}); -``` - -```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": { + "submitters": { "type": "array", + "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { + "role": { "type": "string", - "example": "base64", - "format": "base64", - "description": "Base64-encoded content of the DOCX file or downloadable file URL" + "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": { - "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", + "description": "A list of configurations for document form fields.", "items": { "type": "object", + "required": [ + "name" + ], "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -1859,49 +1478,6 @@ const template = await docuseal.createTemplateFromDocx({ "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": { @@ -1978,6 +1554,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,53 +1616,89 @@ const template = await docuseal.createTemplateFromDocx({ } ], "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" + } } } } - } - } - } - } - } - } -} -``` - -### 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 + }, + "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 template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", documents: [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + name: "Test Document", + html: `

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

+` + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" } ] }); @@ -2091,10 +1712,10 @@ const template = await docuseal.createTemplateFromPdf({ } ], "tags": [ - "Templates" + "Submissions" ], - "summary": "Create a template from existing PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a submission from HTML", + "operationId": "createSubmissionFromHtml", "parameters": [], "requestBody": { "required": true, @@ -2103,82 +1724,247 @@ const template = await docuseal.createTemplateFromPdf({ "schema": { "type": "object", "required": [ - "documents" + "documents", + "submitters" ], "properties": { "name": { "type": "string", - "description": "Name of the template", - "example": "Test PDF" + "description": "Name of the document submission", + "example": "Test Submission Document" }, - "folder_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": { "type": "string", - "description": "The folder's name to which the template should be created." + "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" + ] }, - "external_id": { + "completed_redirect_url": { "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" + "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": [ - "name", - "file" + "email" ], "properties": { "name": { "type": "string", - "description": "Name of the document." + "description": "The name of the submitter." }, - "file": { - "example": "base64", + "role": { "type": "string", - "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "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": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "description": "A list of configurations for document form fields.", "items": { "type": "object", - "properties": { + "required": [ + "name" + ], + "properties": { "name": { "type": "string", - "description": "Name of the field." + "description": "Document field name.", + "example": "First Name" }, - "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" - ] + "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" }, - "role": { - "type": "string", - "description": "Role name of the signer." + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false }, "required": { "type": "boolean", - "description": "Indicates if the field is required." + "description": "Set `true` to make the field required." }, "title": { "type": "string", @@ -2188,57 +1974,46 @@ const template = await docuseal.createTemplateFromPdf({ "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." - } + "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." } } }, - "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": { @@ -2275,6 +2050,15 @@ const template = await docuseal.createTemplateFromPdf({ ], "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.", @@ -2328,24 +2112,46 @@ const template = await docuseal.createTemplateFromPdf({ } ], "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 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 + "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 } } } @@ -2355,22 +2161,55 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Merge templates +### Archive a submission -The API endpoint allows you to merge multiple templates with documents and fields into a new combined template. +The API endpoint allows you to archive a submission. ```typescript import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.mergeTemplates({ - template_ids: [ - 321, - 432 +await docuseal.archiveSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } ], - name: "Merged Template" -}); + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### List all submitters + +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 { data, pagination } = await docuseal.listSubmitters({ limit: 10 }); ``` ```json @@ -2381,105 +2220,155 @@ const template = await docuseal.mergeTemplates({ } ], "tags": [ - "Templates" + "Submitters" ], - "summary": "Merge templates", - "operationId": "mergeTemplate", - "parameters": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "template_ids" - ], - "properties": { - "template_ids": { - "type": "array", - "description": "An array of template ids to merge into a new template.", - "items": { - "type": "integer" - }, - "example": [ - 321, - 432 - ] - }, - "name": { - "type": "string", - "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", - "example": "Merged Template" - }, - "folder_name": { - "type": "string", - "description": "The name of the folder in which the merged template should be placed." - }, - "external_id": { - "type": "string", - "description": "Your application-specific unique string key to identify this template within your app." - }, - "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 - }, - "roles": { - "type": "array", - "description": "An array of submitter role names to be used in the merged template.", - "items": { - "type": "string" - }, - "example": [ - "Agent", - "Customer" - ] - } - } - } - } + "summary": "List all submitters", + "operationId": "getSubmitters", + "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", + "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 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 +### Get a submitter +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. ```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: [ +const submitter = await docuseal.getSubmitter(500001); +``` + +```json +{ + "security": [ { - name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + "AuthToken": [] } ], - submitters: [ + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "operationId": "getSubmitter", + "parameters": [ { - role: "First Party", - email: "john.doe@example.com" + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ] +} +``` + +### Update a submitter + +The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submitter = await docuseal.updateSubmitter(500001, { + email: "john.doe@example.com", + fields: [ + { + name: "First Name", + default_value: "Acme" } ] }); @@ -2493,507 +2382,300 @@ const submission = await docuseal.createSubmissionFromPdf({ } ], "tags": [ - "Submissions" + "Submitters" + ], + "summary": "Update a submitter", + "operationId": "updateSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } ], - "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 submitter." + }, + "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." }, "send_email": { "type": "boolean", - "description": "Set `false` to disable signature request emails sending.", - "default": true + "description": "Set `true` to re-send signature request emails." }, "send_sms": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, - "order": { + "reply_to": { "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": "Specify Reply-To address to use in the notification emails." }, - "completed_redirect_url": { - "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, - "bcc_completed": { - "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" }, - "reply_to": { + "completed_redirect_url": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "Submitter specific URL to redirect to after the submission completion." }, - "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" + "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 }, - "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." + "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}}." + } } }, - "documents": { + "fields": { "type": "array", + "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ - "name", - "file" + "name" ], "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." + "description": "Document template field name.", + "example": "First 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" - ] - }, - "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." - } + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" } - } - }, - "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 + ], + "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" }, - "send_sms": { + "readonly": { "type": "boolean", - "description": "Set `true` to send signature request via phone number and SMS.", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "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." + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." }, - "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." - } + "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" } - }, - "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 - } + ], + "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." } } }, - "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}}." + "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 - }, - "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 } } } @@ -3003,38 +2685,118 @@ const submission = await docuseal.createSubmissionFromPdf({ } ``` -### Create a submission from HTML +### List all templates -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 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 submission = await docuseal.createSubmissionFromHtml({ - name: "Test Submission Document", - documents: [ +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +``` + +```json +{ + "security": [ { - name: "Test Document", - html: `

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

-` + "AuthToken": [] } ], - submitters: [ + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ { - role: "First Party", - email: "john.doe@example.com" + "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 @@ -3045,250 +2807,162 @@ and typesetting industry

} ], "tags": [ - "Submissions" + "Templates" ], - "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": { + "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: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "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": "Specify BCC address to send signed documents to after the completion." + "description": "Name of the template", + "example": "Test PDF" }, - "reply_to": { + "folder_name": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "description": "The folder's name to which the template should be created." }, - "expire_at": { + "external_id": { "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" + "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" }, - "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." - } + "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 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" + "name", + "file" ], "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." + "description": "Name of the document." }, - "completed_redirect_url": { + "file": { + "example": "base64", "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 + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", - "description": "A list of configurations for document form fields.", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", - "required": [ - "name" - ], "properties": { "name": { "type": "string", - "description": "Document field name.", - "example": "First Name" + "description": "Name of the field." }, - "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" + "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" + ] }, - "readonly": { - "type": "boolean", - "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", - "default": false + "role": { + "type": "string", + "description": "Role name of the signer." }, "required": { "type": "boolean", - "description": "Set `true` to make the field required." + "description": "Indicates if the field is required." }, "title": { "type": "string", @@ -3298,6 +2972,57 @@ and typesetting industry

"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": { @@ -3374,6 +3099,15 @@ and typesetting industry

], "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.", @@ -3427,39 +3161,31 @@ and typesetting industry

} ], "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": { + "flatten": { "type": "boolean", - "description": "Set `true` to merge the documents into a single PDF file.", + "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 } } } @@ -3469,9 +3195,9 @@ and typesetting industry

} ``` -### Create a template from PDF +### Create a template from Word DOCX -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 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 ```typescript @@ -3479,26 +3205,12 @@ import docuseal from "@docuseal/api"; docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); -const template = await docuseal.createTemplateFromPdf({ - name: "Test PDF", +const template = await docuseal.createTemplateFromDocx({ + name: "Test DOCX", documents: [ { name: "string", - file: "base64", - fields: [ - { - name: "string", - areas: [ - { - x: 0, - y: 0, - w: 0, - h: 0, - page: 1 - } - ] - } - ] + file: "base64" } ] }); @@ -3514,8 +3226,8 @@ const template = await docuseal.createTemplateFromPdf({ "tags": [ "Templates" ], - "summary": "Create a template from PDF", - "operationId": "createTemplateFromPdf", + "summary": "Create a template from Word DOCX", + "operationId": "createTemplateFromDocx", "parameters": [], "requestBody": { "required": true, @@ -3530,17 +3242,17 @@ const template = await docuseal.createTemplateFromPdf({ "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." + "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 PDF.", + "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.", @@ -3560,14 +3272,14 @@ const template = await docuseal.createTemplateFromPdf({ "description": "Name of the document." }, "file": { - "example": "base64", "type": "string", + "example": "base64", "format": "base64", - "description": "Base64-encoded content of the PDF file or downloadable file URL." + "description": "Base64-encoded content of the DOCX file or downloadable file URL" }, "fields": { - "type": "array", "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", "items": { "type": "object", "properties": { @@ -3595,7 +3307,8 @@ const template = await docuseal.createTemplateFromPdf({ "stamp", "payment", "phone", - "verification" + "verification", + "strikethrough" ] }, "role": { @@ -3618,13 +3331,6 @@ const template = await docuseal.createTemplateFromPdf({ "type": "array", "items": { "type": "object", - "required": [ - "x", - "y", - "w", - "h", - "page" - ], "properties": { "x": { "type": "number", @@ -3644,8 +3350,7 @@ const template = await docuseal.createTemplateFromPdf({ }, "page": { "type": "integer", - "description": "Page number of the field area. Starts from 1.", - "example": 1 + "description": "Page number of the field area. Starts from 1." }, "option": { "type": "string", @@ -3741,6 +3446,15 @@ const template = await docuseal.createTemplateFromPdf({ ], "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.", @@ -3794,6 +3508,13 @@ const template = await docuseal.createTemplateFromPdf({ } ], "default": false + }, + "reasons": { + "description": "An array of signature reasons to choose from.", + "type": "array", + "items": { + "type": "string" + } } } } @@ -3802,16 +3523,6 @@ const template = await docuseal.createTemplateFromPdf({ } } } - }, - "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 } } } @@ -3821,47 +3532,41 @@ const template = await docuseal.createTemplateFromPdf({ } ``` -### Create a submission from DOCX +### Create a template from HTML -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 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 submission = await docuseal.createSubmissionFromDocx({ - name: "Test Submission Document", - variables: { - variable_name: "value" - }, - documents: [ +const template = await docuseal.createTemplateFromHtml({ + html: `

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

+`, + name: "Test Template" +}); +``` + +```json +{ + "security": [ { - name: "string", - file: "base64" - } - ], - submitters: [ - { - role: "First Party", - email: "john.doe@example.com" - } - ] -}); -``` - -```json -{ - "security": [ - { - "AuthToken": [] + "AuthToken": [] } ], "tags": [ - "Submissions" + "Templates" ], - "summary": "Create a submission from DOCX", - "operationId": "createSubmissionFromDocx", + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", "parameters": [], "requestBody": { "required": true, @@ -3870,394 +3575,415 @@ const submission = await docuseal.createSubmissionFromDocx({ "schema": { "type": "object", "required": [ - "documents", - "submitters" + "html" ], "properties": { - "name": { + "html": { "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 + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "variables": { - "type": "object", - "description": "Dynamic content variables object", - "example": { - "variable_name": "value" - } + "html_header": { + "type": "string", + "description": "HTML template of the header to be displayed on every page." }, - "order": { + "html_footer": { "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": "HTML template of the footer to be displayed on every page." }, - "completed_redirect_url": { + "name": { "type": "string", - "description": "Specify URL to redirect to after the submission completion." + "description": "Template name. Random uuid will be assigned when not specified.", + "example": "Test Template" }, - "bcc_completed": { + "size": { "type": "string", - "description": "Specify BCC address to send signed documents to after the completion." + "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" }, - "reply_to": { + "external_id": { "type": "string", - "description": "Specify Reply-To address to use in the notification emails." + "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" }, - "expire_at": { + "folder_name": { "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" + "description": "The folder's name to which the template should be created." }, - "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." - } + "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": { - "name": { + "html": { "type": "string", - "description": "Name of the document." + "description": "HTML template with field tags.", + "example": "

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

\n" }, - "file": { - "example": "base64", + "name": { "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." + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" } } } + } + } + } + } + } + } +} +``` + +### 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" }, - "submitters": { + "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. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.mergeTemplates({ + template_ids: [ + 321, + 432 + ], + name: "Merged Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "operationId": "mergeTemplate", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_ids" + ], + "properties": { + "template_ids": { "type": "array", - "description": "The list of submitters for the submission.", + "description": "An array of template ids to merge into a new template.", "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 - } - } - } - } - } + "type": "integer" + }, + "example": [ + 321, + 432 + ] + }, + "name": { + "type": "string", + "description": "Template name. Existing name with (Merged) suffix will be used if not specified.", + "example": "Merged Template" + }, + "folder_name": { + "type": "string", + "description": "The name of the folder in which the merged template should be placed." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + }, + "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 + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + +### 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." + } + } + } + } + } + } +} +``` + +### 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. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.updateTemplateDocuments(1000001, { + documents: [ + { + file: "string" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "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" }, - "roles": { - "type": "array", - "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", - "items": { - "type": "string" - } + "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`." } } } }, - "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": { + "merge": { "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." } } } @@ -4267,3 +3993,42 @@ const submission = await docuseal.createSubmissionFromDocx({ } ``` +### 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 + } + ] +} +``` + 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." } } }