diff --git a/docs/api/csharp.md b/docs/api/csharp.md new file mode 100644 index 00000000..b0b68b36 --- /dev/null +++ b/docs/api/csharp.md @@ -0,0 +1,2238 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Delete); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/1000001"); +var request = new RestRequest("", Method.Put); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### 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 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/1001/documents"); +var request = new RestRequest("", Method.Get); +request.AddHeader("X-Auth-Token", "API_KEY"); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Create submissions from emails + +This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/emails"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"template_id\":1000001,\"emails\":\"hi@docuseal.com, example@docuseal.com\"}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create submissions from emails", + "operationId": "createSubmissionsFromEmails", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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." + }, + "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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/pdf"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/go.md b/docs/api/go.md new file mode 100644 index 00000000..09d65608 --- /dev/null +++ b/docs/api/go.md @@ -0,0 +1,2657 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates" + + req, _ := http.NewRequest("GET", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001" + + req, _ := http.NewRequest("GET", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001" + + req, _ := http.NewRequest("DELETE", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/1000001" + + payload := strings.NewReader("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") + + req, _ := http.NewRequest("PUT", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```go +package main + +import ( + "fmt" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/1001" + + req, _ := http.NewRequest("GET", url, nil) + + req.Header.Add("X-Auth-Token", "API_KEY") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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": { + "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. + +```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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/pdf" + + payload := strings.NewReader("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/java.md b/docs/api/java.md new file mode 100644 index 00000000..5a1adb66 --- /dev/null +++ b/docs/api/java.md @@ -0,0 +1,2219 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/templates") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/templates/1000001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```java +HttpResponse response = Unirest.delete("https://api.docuseal.com/templates/1000001") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```java +HttpResponse response = Unirest.put("https://api.docuseal.com/templates/1000001") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"New Document Name\",\"folder_name\":\"New Folder\"}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### 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 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```java +HttpResponse response = Unirest.get("https://api.docuseal.com/submissions/1001/documents") + .header("X-Auth-Token", "API_KEY") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Create submissions from emails + +This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/emails") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"template_id\":1000001,\"emails\":\"hi@docuseal.com, example@docuseal.com\"}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create submissions from emails", + "operationId": "createSubmissionsFromEmails", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/pdf") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/javascript.md b/docs/api/javascript.md new file mode 100644 index 00000000..ab7b5518 --- /dev/null +++ b/docs/api/javascript.md @@ -0,0 +1,2315 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +await docuseal.archiveTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.updateTemplate(1000001, { + name: "New Document Name", + folder_name: "New Folder" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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 +{ + "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. + +```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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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": [ + { + "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. + +```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" + }, + "file": { + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." + } + } + } + }, + "merge": { + "type": "boolean", + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." + } + } + } + } + } + } +} +``` + +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.cloneTemplate(1000001, { + name: "Cloned Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + +### Create a template from HTML + +The API endpoint provides the functionality to seamlessly generate a PDF document template by utilizing the provided HTML content while incorporating pre-defined fields.
Related Guides
Create PDF document fillable form with HTML + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromHtml({ + html: `

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

+`, + name: "Test Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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": "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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/nodejs.md b/docs/api/nodejs.md new file mode 100644 index 00000000..5e052f72 --- /dev/null +++ b/docs/api/nodejs.md @@ -0,0 +1,2420 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const { data, pagination } = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "DELETE", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/1000001", { + method: "PUT", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "New Document Name", + folder_name: "New Folder" + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/1001", { + method: "GET", + headers: { + "X-Auth-Token": "API_KEY" + } +}); + +const submission = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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": { + "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. + +```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." + }, + "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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/pdf", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test PDF", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/php.md b/docs/api/php.md new file mode 100644 index 00000000..e6911f02 --- /dev/null +++ b/docs/api/php.md @@ -0,0 +1,2277 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->listTemplates(['limit' => 10]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->archiveTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->updateTemplate(1000001, [ + 'name' => 'New Document Name', + 'folder_name' => 'New Folder' +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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 +{ + "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. + +```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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->listSubmitters(['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." + } + ] +} +``` + +### 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" + }, + "file": { + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." + } + } + } + }, + "merge": { + "type": "boolean", + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." + } + } + } + } + } + } +} +``` + +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->cloneTemplate(1000001, [ + 'name' => 'Cloned Template' +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + +### Create a template from HTML + +The API endpoint provides the functionality to seamlessly generate a PDF document template by utilizing the provided HTML content while incorporating pre-defined fields.
Related Guides
Create PDF document fillable form with HTML + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->createTemplateFromHtml([ + 'html' => '

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

+', + 'name' => 'Test Template' +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 + ] + ] + ] + ] + ] + ] +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/python.md b/docs/api/python.md new file mode 100644 index 00000000..f0060e3f --- /dev/null +++ b/docs/api/python.md @@ -0,0 +1,2334 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.list_submissions({ "limit": 10 }) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.get_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.archive_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.update_template(1000001, { + "name": "New Document Name", + "folder_name": "New Folder" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.get_submission(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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 +{ + "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. + +```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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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." + } + ] +} +``` + +### 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" + }, + "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", + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/ruby.md b/docs/api/ruby.md new file mode 100644 index 00000000..e0f21818 --- /dev/null +++ b/docs/api/ruby.md @@ -0,0 +1,2334 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.list_templates(limit: 10) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.get_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.archive_template(1000001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.update_template(1000001, { + name: "New Document Name", + folder_name: "New Folder" +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.get_submission(1001) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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 +{ + "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. + +```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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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." + } + ] +} +``` + +### 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" + }, + "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", + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/shell.md b/docs/api/shell.md new file mode 100644 index 00000000..ec286be1 --- /dev/null +++ b/docs/api/shell.md @@ -0,0 +1,2219 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```shell +curl --request GET \ + --url https://api.docuseal.com/templates \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```shell +curl --request GET \ + --url https://api.docuseal.com/templates/1000001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```shell +curl --request DELETE \ + --url https://api.docuseal.com/templates/1000001 \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```shell +curl --request PUT \ + --url https://api.docuseal.com/templates/1000001 \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"New Document Name","folder_name":"New Folder"}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### 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 + } + ] +} +``` + +### Get submission documents + +This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned. + +```shell +curl --request GET \ + --url https://api.docuseal.com/submissions/1001/documents \ + --header 'X-Auth-Token: API_KEY' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### Create submissions from emails + +This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools. + +```shell +curl --request POST \ + --url https://api.docuseal.com/submissions/emails \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"template_id":1000001,"emails":"hi@docuseal.com, example@docuseal.com"}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create submissions from emails", + "operationId": "createSubmissionsFromEmails", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```shell +curl --request POST \ + --url https://api.docuseal.com/templates/pdf \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test PDF","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/api/typescript.md b/docs/api/typescript.md new file mode 100644 index 00000000..9ee334ce --- /dev/null +++ b/docs/api/typescript.md @@ -0,0 +1,2315 @@ +### List all templates + +The API endpoint provides the ability to retrieve a list of available document templates. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const { data, pagination } = await docuseal.listTemplates({ limit: 10 }); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "operationId": "getTemplates", + "parameters": [ + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates based on the name partial match." + }, + { + "name": "slug", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by unique slug.", + "example": "opaKWh8WWTAcVG" + }, + { + "name": "external_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." + }, + { + "name": "folder", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter templates by folder name." + }, + { + "name": "archived", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + }, + "description": "Get only archived templates instead of active ones." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The number of templates to return. Default value is 10. Maximum value is 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." + } + ] +} +``` + +### Get a template + +The API endpoint provides the functionality to retrieve information about a document template. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.getTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Archive a template + +The API endpoint allows you to archive a document template. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +await docuseal.archiveTemplate(1000001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ] +} +``` + +### Update a template + +The API endpoint provides the functionality to move a document template to a different folder and update the name of the template. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.updateTemplate(1000001, { + name: "New Document Name", + folder_name: "New Folder" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "operationId": "updateTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the template", + "example": "New Document Name" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be moved.", + "example": "New Folder" + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to update the template with.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + }, + "archived": { + "type": "boolean", + "description": "Set `false` to unarchive template." + } + } + } + } + } + } +} +``` + +### List all submissions + +The API endpoint provides the ability to retrieve a list of available submissions. + +```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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + } +} +``` + +### Get a submission + +The API endpoint provides the functionality to retrieve information about a submission. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.getSubmission(1001); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ] +} +``` + +### 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 +{ + "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. + +```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", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + } +} +``` + +### Get a submitter + +The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values. + +```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." + }, + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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. + +```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": [ + { + "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. + +```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" + }, + "file": { + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL. Leave it empty if you create a new document using HTML param." + }, + "html": { + "type": "string", + "description": "HTML template with field tags. Leave it empty if you add a document via PDF or DOCX base64 encoded file param or URL." + }, + "position": { + "type": "integer", + "description": "Position of the document. By default will be added as the last document in the template.", + "example": 0 + }, + "replace": { + "type": "boolean", + "default": false, + "description": "Set to `true` to replace existing document with a new file at `position`. Existing document fields will be transferred to the new document if it doesn't contain any fields." + }, + "remove": { + "type": "boolean", + "default": false, + "description": "Set to `true` to remove existing document at given `position` or with given `name`." + } + } + } + }, + "merge": { + "type": "boolean", + "default": false, + "description": "Set to `true` to merge all existing and new documents into a single PDF document in the template." + } + } + } + } + } + } +} +``` + +### Clone a template + +The API endpoint allows you to clone existing template into a new template. + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.cloneTemplate(1000001, { + name: "Cloned Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "operationId": "cloneTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the documents template.", + "example": 1000001 + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", + "example": "Cloned Template" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be cloned." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app." + } + } + } + } + } + } +} +``` + +### Create a template from HTML + +The API endpoint provides the functionality to seamlessly generate a PDF document template by utilizing the provided HTML content while incorporating pre-defined fields.
Related Guides
Create PDF document fillable form with HTML + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromHtml({ + html: `

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

+`, + name: "Test Template" +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from HTML", + "operationId": "createTemplateFromHtml", + "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." + }, + "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 + + +```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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +### Create a template from existing PDF + +The API endpoint provides the functionality to create a fillable document template for existing PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 existing PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + } +} +``` + +### 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": "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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + } +} +``` + diff --git a/docs/embedding/form-builder-angular.md b/docs/embedding/form-builder-angular.md new file mode 100644 index 00000000..61346f60 --- /dev/null +++ b/docs/embedding/form-builder-angular.md @@ -0,0 +1,513 @@ +# Angular Form Builder + +### Example Code + +```angular +import { Component, OnInit } from '@angular/core'; +import { HttpClient } from '@angular/common/http'; +import { DocusealBuilderComponent } from '@docuseal/angular'; + +@Component({ + selector: 'app-root', + standalone: true, + imports: [DocusealBuilderComponent], + template: ` +
+ + + +
+ ` +}) +export class AppComponent implements OnInit { + token: string = '' + + constructor(private http: HttpClient) {} + + ngOnInit() { + this.http.post('/api/docuseal/builder_token', {}).subscribe((data: any) => { + this.token = data.token; + }); + } +} + +``` + +```javascript +const jwt = require('jsonwebtoken'); + +const token = jwt.sign({ + user_email: '{{admin_user_email}}', + integration_email: '{{signer_email}}', + external_id: 'TestForm123', + name: 'Integration W-9 Test Form', + document_urls: ['https://www.irs.gov/pub/irs-pdf/fw9.pdf'], +}, '{{api_key}}'); + +``` + +### Attributes + +```json +{ + "token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key.
Ensure that the JWT token is generated on the backend to prevent unauthorized access to your documents.", + "required": true, + "properties": { + "user_email": { + "type": "string", + "required": true, + "description": "Email of the owner of the API signing key - admin user email." + }, + "integration_email": { + "type": "string", + "required": false, + "description": "Email of the user to create a template for.", + "example": "signer@example.com" + }, + "template_id": { + "type": "number", + "required": false, + "description": "ID of the template to open in the form builder. Optional when `document_urls` are specified." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app.", + "required": false + }, + "folder_name": { + "type": "string", + "description": "The folder name in which the template should be created.", + "required": false + }, + "document_urls": { + "type": "array", + "required": false, + "description": "An Array of URLs with PDF files to open in the form builder. Optional when `template_id` is specified.", + "example": "['https://www.irs.gov/pub/irs-pdf/fw9.pdf']" + }, + "name": { + "type": "string", + "required": false, + "description": "New template name when creating a template with document_urls specified.", + "example": "Integration W-9 Test Form" + }, + "extract_fields": { + "type": "boolean", + "required": false, + "description": "Pass `false` to disable automatic PDF form fields extraction. PDF fields are automatically added by default." + } + } + }, + "host": { + "type": "string", + "required": false, + "description": "DocuSeal host domain name. Only use this attribute if you are using the on-premises DocuSeal installation or docuseal.eu Cloud.", + "example": "yourdomain.com" + }, + "customButton": { + "type": "object", + "required": false, + "description": "Custom button will be displayed on the top right corner of the form builder.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Custom button title." + }, + "url": { + "type": "string", + "required": true, + "description": "Custom button URL. Only absolute URLs are supported." + } + } + }, + "roles": { + "type": "array", + "required": false, + "description": "Submitter role names to be used by default in the form." + }, + "fieldTypes": { + "type": "array", + "required": false, + "description": "Field type names to be used in the form builder. All field types are used by default." + }, + "drawFieldType": { + "type": "string", + "required": false, + "default": "text", + "description": "Field type to be used by default with the field drawing tool.", + "example": "signature" + }, + "fields": { + "type": "array", + "required": false, + "description": "An array of default custom field properties with `name` to be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "submitters": { + "type": "array", + "required": false, + "description": "An array of default submitters with `role` name to be added to the document.", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "required": false, + "description": "Submitter email." + }, + "role": { + "type": "string", + "required": true, + "description": "Submitter role name." + }, + "name": { + "type": "string", + "required": false, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "required": false, + "description": "Submitter phone number, formatted according to the E.164 standard." + } + } + } + }, + "requiredFields": { + "type": "array", + "required": false, + "description": "An array of default required custom field properties with `name` that should be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "emailMessage": { + "type": "object", + "required": false, + "description": "Email subject and body for the signature request.", + "properties": { + "subject": { + "type": "string", + "required": true, + "description": "Email subject for the signature request." + }, + "body": { + "type": "string", + "required": true, + "description": "Email body for the signature request." + } + } + }, + "withTitle": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove document title from the builder." + }, + "withSendButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Send\" button." + }, + "withUploadButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Upload\" button." + }, + "withAddPageButton": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show the \"Add Blank Page\" button." + }, + "withSignYourselfButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Sign Yourself\" button." + }, + "withDocumentsList": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the documents list on the left. Documents list is displayed by default." + }, + "withFieldsList": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." + }, + "withFieldPlaceholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "onlyDefinedFields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow to add fields only defined in the `fields` prop." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show template in preview mode without ability to edit it." + }, + "autosave": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable form changes autosaving." + }, + "language": { + "type": "string", + "required": false, + "default": "en", + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See template_builder/i18n.js for available i18n keys." + }, + "backgroundColor": { + "type": "string", + "required": false, + "description": "The form builder background color. Only HEX color codes are supported.", + "example": "#ffffff" + }, + "customCss": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form builder.", + "example": "#sign_yourself_button { background-color: #FFA500; }" + } +} +``` + +### Callback + +```json +{ + "onLoad": { + "type": "event emitter", + "required": false, + "description": "Event emitted on loading the form builder template data.", + "example": "handleLoad($event)" + }, + "onUpload": { + "type": "event emitter", + "required": false, + "description": "Event emitted on uploading a document to the template.", + "example": "handleUpload($event)" + }, + "onSend": { + "type": "event emitter", + "required": false, + "description": "Event emitted on sending documents for signature to recipients.", + "example": "handleSend($event)" + }, + "onChange": { + "type": "function", + "required": false, + "description": "Function to be called when changes are made to the template form.", + "example": "handleChange($event)" + }, + "onSave": { + "type": "event emitter", + "required": false, + "description": "Event emitted on saving changes of the template form.", + "example": "handleSave($event)" + } +} +``` diff --git a/docs/embedding/form-builder-javascript.md b/docs/embedding/form-builder-javascript.md new file mode 100644 index 00000000..ecd795b1 --- /dev/null +++ b/docs/embedding/form-builder-javascript.md @@ -0,0 +1,477 @@ +# JavaScript Form Builder + +### Example Code + +```javascript + + + + + +``` + +### Attributes + +```json +{ + "data-token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key.
Ensure that the JWT token is generated on the backend to prevent unauthorized access to your documents.", + "required": true, + "properties": { + "user_email": { + "type": "string", + "required": true, + "description": "Email of the owner of the API signing key - admin user email." + }, + "integration_email": { + "type": "string", + "required": false, + "description": "Email of the user to create a template for.", + "example": "signer@example.com" + }, + "template_id": { + "type": "number", + "required": false, + "description": "ID of the template to open in the form builder. Optional when `document_urls` are specified." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app.", + "required": false + }, + "folder_name": { + "type": "string", + "description": "The folder name in which the template should be created.", + "required": false + }, + "document_urls": { + "type": "array", + "required": false, + "description": "An Array of URLs with PDF files to open in the form builder. Optional when `template_id` is specified.", + "example": "['https://www.irs.gov/pub/irs-pdf/fw9.pdf']" + }, + "name": { + "type": "string", + "required": false, + "description": "New template name when creating a template with document_urls specified.", + "example": "Integration W-9 Test Form" + }, + "extract_fields": { + "type": "boolean", + "required": false, + "description": "Pass `false` to disable automatic PDF form fields extraction. PDF fields are automatically added by default." + } + } + }, + "data-host": { + "type": "string", + "required": false, + "description": "DocuSeal host domain name. Only use this attribute if you are using the on-premises DocuSeal installation or docuseal.eu Cloud.", + "example": "yourdomain.com" + }, + "data-roles": { + "type": "string", + "required": false, + "description": "Comma separated submitter role names to be used by default in the form.", + "example": "Company,Customer" + }, + "data-fields": { + "type": "string", + "doc_type": "array", + "required": false, + "description": "A list of default custom fields with `name` to be added to the document. Should contain an array of field properties as a JSON encoded string.", + "example": "[{ \"name\": \"FIELD_1\", \"type\": \"date\", \"role\": \"Customer\", \"default_value\": \"2021-01-01\" }]", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "data-submitters": { + "type": "string", + "doc_type": "array", + "required": false, + "description": "A list of default submitters with `role` name to be added to the document. Should contain an array of field properties as a JSON encoded string.", + "example": "[{ \"email\": \"example@company.com\", \"name\": \"John Doe\", \"phone\": \"+1234567890\", \"role\": \"Customer\" }]", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "required": false, + "description": "Submitter email." + }, + "role": { + "type": "string", + "required": true, + "description": "Submitter role name." + }, + "name": { + "type": "string", + "required": false, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "required": false, + "description": "Submitter phone number, formatted according to the E.164 standard." + } + } + } + }, + "data-required-fields": { + "type": "string", + "doc_type": "array", + "required": false, + "description": "A list of required default custom fields with `name` that should be added to the document. Should contain an array of field properties as a JSON encoded string.", + "example": "[{ \"name\": \"FIELD_1\", \"type\": \"date\", \"role\": \"Customer\", \"default_value\": \"2021-01-01\" }]", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "data-field-types": { + "type": "string", + "required": false, + "description": "Comma separated field type names to be used in the form builder. All field types are used by default.", + "example": "text,date" + }, + "data-draw-field-type": { + "type": "string", + "required": false, + "default": "text", + "description": "Field type to be used by default with the field drawing tool.", + "example": "signature" + }, + "data-custom-button-title": { + "type": "string", + "required": false, + "description": "Custom button title. This button will be displayed on the top right corner of the form builder." + }, + "data-custom-button-url": { + "type": "string", + "required": false, + "description": "Custom button URL. Only absolute URLs are supported." + }, + "data-with-title": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove document title from the builder." + }, + "email-subject": { + "type": "string", + "required": false, + "description": "Email subject for the signature request. Required if `email-body` specified" + }, + "email-body": { + "type": "string", + "required": false, + "description": "Email body for the signature request. Required if `email-subject` specified" + }, + "data-with-send-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Recipients\" button." + }, + "data-with-upload-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Upload\" button." + }, + "data-with-add-page-button": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show the \"Add Blank Page\" button." + }, + "data-with-sign-yourself-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Sign Yourself\" button." + }, + "data-with-documents-list": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the documents list on the left. Documents list is displayed by default." + }, + "data-with-fields-list": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." + }, + "data-with-field-placeholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "data-preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show template in preview mode without ability to edit it." + }, + "data-only-defined-fields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow to add fields only defined in the `data-fields` attribute." + }, + "data-autosave": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable form changes autosaving." + }, + "data-i18n": { + "type": "string", + "required": false, + "default": "{}", + "description": "JSON encoded string that contains i18n keys to replace the default UI text with custom values. See template_builder/i18n.js for available i18n keys." + }, + "data-language": { + "type": "string", + "required": false, + "default": "en", + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + }, + "data-background-color": { + "type": "string", + "required": false, + "description": "The form builder background color. Only HEX color codes are supported.", + "example": "#ffffff" + }, + "data-custom-css": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form builder.", + "example": "#sign_yourself_button { background-color: #FFA500; }" + } +} +``` + +### Callback + +```json +{ + "load": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on loading the form builder template data.", + "example": "document.querySelector('docuseal-builder').addEventListener('load', (e) => e.detail)" + }, + "upload": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on uploading a document to the template.", + "example": "document.querySelector('docuseal-builder').addEventListener('upload', (e) => e.detail)" + }, + "send": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on sending documents for signature to recipients.", + "example": "document.querySelector('docuseal-builder').addEventListener('send', (e) => e.detail)" + }, + "change": { + "type": "event", + "required": false, + "description": "Custom event to be triggered every time a change to the template is made.", + "example": "document.querySelector('docuseal-builder').addEventListener('change', (e) => e.detail)" + }, + "save": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on saving changes of the template form.", + "example": "document.querySelector('docuseal-builder').addEventListener('save', (e) => e.detail)" + } +} +``` diff --git a/docs/embedding/form-builder-react.md b/docs/embedding/form-builder-react.md new file mode 100644 index 00000000..21bf8efc --- /dev/null +++ b/docs/embedding/form-builder-react.md @@ -0,0 +1,504 @@ +# React Form Builder + +### Example Code + +```react +import React, { useState, useEffect } from 'react'; +import { DocusealBuilder } from '@docuseal/react' + +const App = () => { + const [token, setToken] = useState(); + + useEffect(() => { + fetch('/api/docuseal/builder_token', { + method: 'POST', + }) + .then((response) => response.json()) + .then((data) => { + setToken(data.token); + }); + }, []); + + return token && ; +}; + +``` + +```javascript +const jwt = require('jsonwebtoken'); + +const token = jwt.sign({ + user_email: '{{admin_user_email}}', + integration_email: '{{signer_email}}', + external_id: 'TestForm123', + name: 'Integration W-9 Test Form', + document_urls: ['https://www.irs.gov/pub/irs-pdf/fw9.pdf'], +}, '{{api_key}}'); + +``` + +### Attributes + +```json +{ + "token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key.
Ensure that the JWT token is generated on the backend to prevent unauthorized access to your documents.", + "required": true, + "properties": { + "user_email": { + "type": "string", + "required": true, + "description": "Email of the owner of the API signing key - admin user email." + }, + "integration_email": { + "type": "string", + "required": false, + "description": "Email of the user to create a template for.", + "example": "signer@example.com" + }, + "template_id": { + "type": "number", + "required": false, + "description": "ID of the template to open in the form builder. Optional when `document_urls` are specified." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app.", + "required": false + }, + "folder_name": { + "type": "string", + "description": "The folder name in which the template should be created.", + "required": false + }, + "document_urls": { + "type": "array", + "required": false, + "description": "An Array of URLs with PDF files to open in the form builder. Optional when `template_id` is specified.", + "example": "['https://www.irs.gov/pub/irs-pdf/fw9.pdf']" + }, + "name": { + "type": "string", + "required": false, + "description": "New template name when creating a template with document_urls specified.", + "example": "Integration W-9 Test Form" + }, + "extract_fields": { + "type": "boolean", + "required": false, + "description": "Pass `false` to disable automatic PDF form fields extraction. PDF fields are automatically added by default." + } + } + }, + "host": { + "type": "string", + "required": false, + "description": "DocuSeal host domain name. Only use this attribute if you are using the on-premises DocuSeal installation or docuseal.eu Cloud.", + "example": "yourdomain.com" + }, + "customButton": { + "type": "object", + "required": false, + "description": "Custom button will be displayed on the top right corner of the form builder.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Custom button title." + }, + "url": { + "type": "string", + "required": true, + "description": "Custom button URL. Only absolute URLs are supported." + } + } + }, + "roles": { + "type": "array", + "required": false, + "description": "Submitter role names to be used by default in the form." + }, + "fieldTypes": { + "type": "array", + "required": false, + "description": "Field type names to be used in the form builder. All field types are used by default." + }, + "drawFieldType": { + "type": "string", + "required": false, + "default": "text", + "description": "Field type to be used by default with the field drawing tool.", + "example": "signature" + }, + "fields": { + "type": "array", + "required": false, + "description": "An array of default custom field properties with `name` to be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "submitters": { + "type": "array", + "required": false, + "description": "An array of default submitters with `role` name to be added to the document.", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "required": false, + "description": "Submitter email." + }, + "role": { + "type": "string", + "required": true, + "description": "Submitter role name." + }, + "name": { + "type": "string", + "required": false, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "required": false, + "description": "Submitter phone number, formatted according to the E.164 standard." + } + } + } + }, + "requiredFields": { + "type": "array", + "required": false, + "description": "An array of default required custom field properties with `name` that should be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "emailMessage": { + "type": "object", + "required": false, + "description": "Email subject and body for the signature request.", + "properties": { + "subject": { + "type": "string", + "required": true, + "description": "Email subject for the signature request." + }, + "body": { + "type": "string", + "required": true, + "description": "Email body for the signature request." + } + } + }, + "withTitle": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove document title from the builder." + }, + "withSendButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Send\" button." + }, + "withUploadButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Upload\" button." + }, + "withAddPageButton": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show the \"Add Blank Page\" button." + }, + "withSignYourselfButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Sign Yourself\" button." + }, + "withDocumentsList": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the documents list on the left. Documents list is displayed by default." + }, + "withFieldsList": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." + }, + "withFieldPlaceholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "onlyDefinedFields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow to add fields only defined in the `fields` prop." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show template in preview mode without ability to edit it." + }, + "autosave": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable form changes autosaving." + }, + "language": { + "type": "string", + "required": false, + "default": "en", + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See template_builder/i18n.js for available i18n keys." + }, + "backgroundColor": { + "type": "string", + "required": false, + "description": "The form builder background color. Only HEX color codes are supported.", + "example": "#ffffff" + }, + "customCss": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form builder.", + "example": "#sign_yourself_button { background-color: #FFA500; }" + } +} +``` + +### Callback + +```json +{ + "onLoad": { + "type": "function", + "required": false, + "description": "Function to be called on loading the form builder template data.", + "example": "(data) => { console.log(data) }" + }, + "onUpload": { + "type": "function", + "required": false, + "description": "Function to be called on uploading a document to the template.", + "example": "(data) => { console.log(data) }" + }, + "onSend": { + "type": "function", + "required": false, + "description": "Function to be called on sending documents for signature to recipients.", + "example": "(data) => { console.log(data) }" + }, + "onChange": { + "type": "function", + "required": false, + "description": "Function to be called when changes are made to the template form.", + "example": "(data) => { console.log(data) }" + }, + "onSave": { + "type": "function", + "required": false, + "description": "Function to be called on saving changes of the template form.", + "example": "(data) => { console.log(data) }" + } +} +``` diff --git a/docs/embedding/form-builder-vue.md b/docs/embedding/form-builder-vue.md new file mode 100644 index 00000000..a7194c4e --- /dev/null +++ b/docs/embedding/form-builder-vue.md @@ -0,0 +1,513 @@ +# Vue Form Builder + +### Example Code + +```vue + + + + +``` + +```javascript +const jwt = require('jsonwebtoken'); + +const token = jwt.sign({ + user_email: '{{admin_user_email}}', + integration_email: '{{signer_email}}', + external_id: 'TestForm123', + name: 'Integration W-9 Test Form', + document_urls: ['https://www.irs.gov/pub/irs-pdf/fw9.pdf'], +}, '{{api_key}}'); + +``` + +### Attributes + +```json +{ + "token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key.
Ensure that the JWT token is generated on the backend to prevent unauthorized access to your documents.", + "required": true, + "properties": { + "user_email": { + "type": "string", + "required": true, + "description": "Email of the owner of the API signing key - admin user email." + }, + "integration_email": { + "type": "string", + "required": false, + "description": "Email of the user to create a template for.", + "example": "signer@example.com" + }, + "template_id": { + "type": "number", + "required": false, + "description": "ID of the template to open in the form builder. Optional when `document_urls` are specified." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app.", + "required": false + }, + "folder_name": { + "type": "string", + "description": "The folder name in which the template should be created.", + "required": false + }, + "document_urls": { + "type": "array", + "required": false, + "description": "An Array of URLs with PDF files to open in the form builder. Optional when `template_id` is specified.", + "example": "['https://www.irs.gov/pub/irs-pdf/fw9.pdf']" + }, + "name": { + "type": "string", + "required": false, + "description": "New template name when creating a template with document_urls specified.", + "example": "Integration W-9 Test Form" + }, + "extract_fields": { + "type": "boolean", + "required": false, + "description": "Pass `false` to disable automatic PDF form fields extraction. PDF fields are automatically added by default." + } + } + }, + "host": { + "type": "string", + "required": false, + "description": "DocuSeal host domain name. Only use this attribute if you are using the on-premises DocuSeal installation or docuseal.eu Cloud.", + "example": "yourdomain.com" + }, + "custom-button": { + "type": "object", + "required": false, + "description": "Custom button will be displayed on the top right corner of the form builder.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Custom button title." + }, + "url": { + "type": "string", + "required": true, + "description": "Custom button URL. Only absolute URLs are supported." + } + } + }, + "only-defined-fields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow to add fields only defined in the `:fields` prop." + }, + "with-send-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Recipients\" button." + }, + "roles": { + "type": "array", + "required": false, + "description": "Submitter role names to be used by default in the form." + }, + "field-types": { + "type": "array", + "required": false, + "description": "Field type names to be used in the form builder. All field types are used by default." + }, + "draw-field-type": { + "type": "string", + "required": false, + "default": "text", + "description": "Field type to be used by default with the field drawing tool.", + "example": "signature" + }, + "fields": { + "type": "array", + "required": false, + "description": "An array of default custom field properties with `name` to be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "submitters": { + "type": "array", + "required": false, + "description": "An array of default submitters with `role` name to be added to the document.", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "required": false, + "description": "Submitter email." + }, + "role": { + "type": "string", + "required": true, + "description": "Submitter role name." + }, + "name": { + "type": "string", + "required": false, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "required": false, + "description": "Submitter phone number, formatted according to the E.164 standard." + } + } + } + }, + "required-fields": { + "type": "array", + "required": false, + "description": "An array of default required custom field properties with `name` that should be added to the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "description": "Field name." + }, + "type": { + "type": "string", + "required": false, + "description": "Field type.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "required": false, + "description": "Submitter role name for the field." + }, + "default_value": { + "type": "string", + "required": false, + "description": "Default value of the field." + }, + "title": { + "type": "string", + "required": false, + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "required": false, + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "width": { + "type": "number", + "required": false, + "description": "Field width in pixels." + }, + "height": { + "type": "number", + "required": false, + "description": "Field height in pixels." + }, + "format": { + "type": "string", + "required": false, + "description": "Field format. Depends on the field type." + }, + "options": { + "type": "array", + "required": false, + "description": "Field options. Required for the select field type." + }, + "validation": { + "type": "object", + "required": false, + "description": "Field validation rules.", + "properties": { + "pattern": { + "type": "string", + "required": false, + "description": "Field pattern.", + "example": "^[0-9]{5}$" + }, + "message": { + "type": "string", + "required": false, + "description": "Validation error message." + } + } + } + } + } + }, + "email-message": { + "type": "object", + "required": false, + "description": "Email subject and body for the signature request.", + "properties": { + "subject": { + "type": "string", + "required": true, + "description": "Email subject for the signature request." + }, + "body": { + "type": "string", + "required": true, + "description": "Email body for the signature request." + } + } + }, + "with-title": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove document title from the builder." + }, + "with-upload-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Upload\" button." + }, + "with-add-page-button": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show the \"Add Blank Page\" button." + }, + "with-sign-yourself-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Show the \"Sign Yourself\" button." + }, + "with-documents-list": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the documents list on the left. Documents list is displayed by default." + }, + "with-fields-list": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to now show the fields list on the right. Fields list is displayed by default." + }, + "with-field-placeholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "autosave": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable form changes autosaving." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show template in preview mode without ability to edit it." + }, + "language": { + "type": "string", + "required": false, + "default": "en", + "description": "UI language, 'en', 'es', 'de', 'fr', 'pt', 'he', 'ar' languages are available." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See template_builder/i18n.js for available i18n keys." + }, + "background-color": { + "type": "string", + "required": false, + "description": "The form builder background color. Only HEX color codes are supported.", + "example": "#ffffff" + }, + "custom-css": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form builder.", + "example": "#sign_yourself_button { background-color: #FFA500; }" + } +} +``` + +### Callback + +```json +{ + "@load": { + "type": "function", + "required": false, + "description": "Function to be called on loading the form builder template data.", + "example": "onBuilderLoad" + }, + "@upload": { + "type": "function", + "required": false, + "description": "Function to be called on uploading a document to the template.", + "example": "onBuilderUpload" + }, + "@send": { + "type": "function", + "required": false, + "description": "Function to be called on sending documents for signature to recipients.", + "example": "onBuilderSend" + }, + "@change": { + "type": "function", + "required": false, + "description": "Function to be called when changes are made to the template form.", + "example": "onBuilderChange" + }, + "@save": { + "type": "function", + "required": false, + "description": "Function to be called on saving changes of the template form.", + "example": "onBuilderSave" + } +} +``` diff --git a/docs/embedding/signing-form-angular.md b/docs/embedding/signing-form-angular.md new file mode 100644 index 00000000..63a5a434 --- /dev/null +++ b/docs/embedding/signing-form-angular.md @@ -0,0 +1,295 @@ +# Angular Signing Form + +### Example Code + +```angular +import { Component } from '@angular/core'; +import { DocusealFormComponent } from '@docuseal/angular'; + +@Component({ + selector: 'app-root', + standalone: true, + imports: [DocusealFormComponent], + template: ` +
+ + +
+ ` +}) +export class AppComponent {} + +``` + +### Attributes + +```json +{ + "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.
    • " + }, + "email": { + "type": "string", + "required": false, + "description": "Email address of the signer. Additional email form step will be displayed if the email attribute is not specified." + }, + "name": { + "type": "string", + "required": false, + "description": "Name of the signer." + }, + "role": { + "type": "string", + "required": false, + "description": "The role name or title of the signer.", + "example": "First Party" + }, + "expand": { + "type": "boolean", + "required": false, + "description": "Expand form on open.", + "default": true + }, + "minimize": { + "type": "boolean", + "required": false, + "description": "Set to `true` to always minimize form fields. Requires to click on the field to expand the form.", + "default": false + }, + "orderAsOnPage": { + "type": "boolean", + "required": false, + "default": false, + "description": "Order form fields based on their position on the pages." + }, + "externalId": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "logo": { + "type": "string", + "required": false, + "description": "Public logo image URL to use in the signing form." + }, + "language": { + "type": "string", + "required": false, + "description": "UI language: en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja languages are available. Be default the form is displayed in the user browser language automatically." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See submission_form/i18n.js for available i18n keys." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + }, + "goToLast": { + "type": "boolean", + "required": false, + "default": true, + "description": "Navigate to the last unfinished step." + }, + "withFieldNames": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to hide field name. Hidding field names can be useful for when they are not in the human readable format. Field names are displayed by default." + }, + "withFieldPlaceholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "skipFields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow skipping form fields." + }, + "autoscrollFields": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable auto-scrolling to the next document field." + }, + "sendCopyEmail": { + "type": "boolean", + "required": false, + "description": "Set `false` to disable automatic email sending with signed documents to the signers. Emails with signed documents are sent to the signers by default." + }, + "backgroundColor": { + "type": "string", + "required": false, + "description": "Form background color. Only HEX color codes are supported.", + "example": "#d9d9d9" + }, + "completedRedirectUrl": { + "type": "string", + "required": false, + "description": "URL to redirect to after the submission completion.", + "example": "https://docuseal.com/success" + }, + "completedMessage": { + "type": "object", + "required": false, + "description": "Message displayed after the form completion.", + "properties": { + "title": { + "type": "string", + "required": false, + "description": "Message title.", + "example": "Documents have been signed!" + }, + "body": { + "type": "string", + "required": false, + "description": "Message content.", + "example": "If you have any questions, please contact us." + } + } + }, + "completedButton": { + "type": "object", + "required": false, + "description": "Customizable button after form completion.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Button label.", + "example": "Go Back" + }, + "url": { + "type": "string", + "required": true, + "description": "Button link. Only absolute URLs are supported.", + "example": "https://example.com" + } + } + }, + "withTitle": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the document title from the form." + }, + "withDecline": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the decline button in the form." + }, + "withDownloadButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document download button from the completed form card." + }, + "withSendCopyButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document send email button from the completed form card." + }, + "withCompleteButton": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the complete button in the form header." + }, + "allowToResubmit": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow user to re-submit the form." + }, + "signature": { + "type": "string", + "required": false, + "description": "Allows pre-filling signature fields. The value can be a base64 encoded image string, a public URL to an image, or plain text that will be rendered as a typed signature using a standard font." + }, + "rememberSignature": { + "type": "boolean", + "required": false, + "description": "Allows to specify whether the signature should be remembered for future use. Remembered signatures are stored in the signer's browser local storage and can be automatically reused to prefill signature fields in new forms for the signer when the value is set to `true`." + }, + "reuseSignature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to not reuse the signature in the second signature field and collect a new one." + }, + "allowTypedSignature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow users to type their signature." + }, + "values": { + "type": "object", + "required": false, + "description": "Pre-assigned values for form fields.", + "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" + }, + "metadata": { + "type": "object", + "required": false, + "description": "Metadata object with additional signer information.", + "example": "{ customData: 'custom value' }" + }, + "readonlyFields": { + "type": "array", + "required": false, + "description": "List of read-only fields.", + "example": "['First Name','Last Name']" + }, + "customCss": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form.", + "example": "#submit_form_button { background-color: #d9d9d9; }" + } +} +``` + +### Callback + +```json +{ + "onInit": { + "type": "event emitter", + "required": false, + "description": "Event emitted on initializing the form component.", + "example": "handleInit($event)" + }, + "onLoad": { + "type": "event emitter", + "required": false, + "description": "Event emitted on loading the form data.", + "example": "handleLoad($event)" + }, + "onComplete": { + "type": "event emitter", + "required": false, + "description": "Event emitted the form completion.", + "example": "handleComplete($event)" + }, + "onDecline": { + "type": "event emitter", + "required": false, + "description": "Event emitted after the form decline.", + "example": "handleDecline($event)" + } +} +``` diff --git a/docs/embedding/signing-form-javascript.md b/docs/embedding/signing-form-javascript.md new file mode 100644 index 00000000..05d375aa --- /dev/null +++ b/docs/embedding/signing-form-javascript.md @@ -0,0 +1,275 @@ +# JavaScript Signing Form + +### Example Code + +```javascript + + + + + + + +``` + +### Attributes + +```json +{ + "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.
    • " + }, + "data-email": { + "type": "string", + "required": false, + "description": "Email address of the signer. Additional email form step will be displayed if the email attribute is not specified." + }, + "data-name": { + "type": "string", + "required": false, + "description": "Name of the signer." + }, + "data-role": { + "type": "string", + "required": false, + "description": "The role name or title of the signer.", + "example": "First Party" + }, + "data-expand": { + "type": "boolean", + "required": false, + "description": "Expand form on open.", + "default": true + }, + "data-minimize": { + "type": "boolean", + "required": false, + "description": "Set to `true` to always minimize form fields. Requires to click on the field to expand the form.", + "default": false + }, + "data-order-as-on-page": { + "type": "boolean", + "required": false, + "default": false, + "description": "Order form fields based on their position on the pages." + }, + "data-preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + }, + "data-logo": { + "type": "string", + "required": false, + "description": "Public logo image URL to use in the signing form." + }, + "data-language": { + "type": "string", + "required": false, + "description": "UI language: en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja languages are available. Be default the form is displayed in the user browser language automatically." + }, + "data-i18n": { + "type": "string", + "required": false, + "default": "{}", + "description": "JSON encoded string that contains i18n keys to replace the default UI text with custom values. See submission_form/i18n.js for available i18n keys." + }, + "data-go-to-last": { + "type": "boolean", + "required": false, + "default": true, + "description": "Navigate to the last unfinished step." + }, + "data-skip-fields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow skipping form fields." + }, + "data-autoscroll-fields": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable auto-scrolling to the next document field." + }, + "data-send-copy-email": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable automatic email sending with signed documents to the signers. Emails with signed documents are sent to the signers by default." + }, + "data-with-title": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the document title from the form." + }, + "data-with-decline": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the decline button in the form." + }, + "data-with-field-names": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to hide field name. Hidding field names can be useful for when they are not in the human readable format. Field names are displayed by default." + }, + "data-with-field-placeholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "data-with-download-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document download button from the completed form card." + }, + "data-with-send-copy-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document send email button from the completed form card." + }, + "data-with-complete-button": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the complete button in the form header." + }, + "data-allow-to-resubmit": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow users to re-submit the form." + }, + "data-allow-typed-signature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow users to type their signature." + }, + "data-signature": { + "type": "string", + "required": false, + "description": "Allows pre-filling signature fields. The value can be a base64 encoded image string, a public URL to an image, or plain text that will be rendered as a typed signature using a standard font." + }, + "data-remember-signature": { + "type": "boolean", + "required": false, + "description": "Allows to specify whether the signature should be remembered for future use. Remembered signatures are stored in the signer's browser local storage and can be automatically reused to prefill signature fields in new forms for the signer when the value is set to `true`." + }, + "data-reuse-signature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to not reuse the signature in the second signature field and collect a new one." + }, + "data-background-color": { + "type": "string", + "required": false, + "description": "Form background color. Only HEX color codes are supported.", + "example": "#d9d9d9" + }, + "data-values": { + "type": "object", + "required": false, + "description": "Pre-assigned values for form fields.", + "example": "{\"First Name\":\"Jon\",\"Last Name\":\"Doe\"}" + }, + "data-external-id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "data-metadata": { + "type": "object", + "required": false, + "description": "Signer metadata Object in JSON format. ", + "example": "{\"customData\":\"customValue\"}" + }, + "data-readonly-fields": { + "type": "string", + "required": false, + "description": "Comma separated read-only field names", + "example": "First Name,Last Name" + }, + "data-completed-redirect-url": { + "type": "string", + "required": false, + "description": "URL to redirect to after the submission completion.", + "example": "https://docuseal.com/success" + }, + "data-completed-message-title": { + "type": "string", + "required": false, + "description": "Message title displayed after the form completion.", + "example": "Documents have been completed" + }, + "data-completed-message-body": { + "type": "string", + "required": false, + "description": "Message body displayed after the form completion.", + "example": "If you have any questions, please contact us." + }, + "data-completed-button-title": { + "type": "string", + "required": false, + "description": "Button title displayed after the form completion.", + "example": "Go Back" + }, + "data-completed-button-url": { + "type": "string", + "required": false, + "description": "URL of the button displayed after the form completion.", + "example": "https://example.com" + }, + "data-custom-css": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form.", + "example": "#submit_form_button { background-color: #d9d9d9; }" + } +} +``` + +### Callback + +```json +{ + "init": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on initializing the form component.", + "example": "document.querySelector('docuseal-form').addEventListener('init', () => console.log('init'))" + }, + "load": { + "type": "event", + "required": false, + "description": "Custom event to be triggered on loading the form data.", + "example": "document.querySelector('docuseal-form').addEventListener('load', (e) => e.detail)" + }, + "completed": { + "type": "event", + "required": false, + "description": "Custom event to be triggered after form completion.", + "example": "document.querySelector('docuseal-form').addEventListener('completed', (e) => e.detail)" + }, + "declined": { + "type": "event", + "description": "Custom event to be triggered after form decline.", + "example": "document.querySelector('docuseal-form').addEventListener('declined', (e) => e.detail)" + } +} +``` diff --git a/docs/embedding/signing-form-react.md b/docs/embedding/signing-form-react.md new file mode 100644 index 00000000..8c0c1f9b --- /dev/null +++ b/docs/embedding/signing-form-react.md @@ -0,0 +1,292 @@ +# React Signing Form + +### Example Code + +```react +import React from "react" +import { DocusealForm } from '@docuseal/react' + +export function App() { + return ( +
    + console.log(data)} + /> +
    + ); +} + +``` + +### Attributes + +```json +{ + "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.
    • " + }, + "email": { + "type": "string", + "required": false, + "description": "Email address of the signer. Additional email form step will be displayed if the email attribute is not specified." + }, + "name": { + "type": "string", + "required": false, + "description": "Name of the signer." + }, + "role": { + "type": "string", + "required": false, + "description": "The role name or title of the signer.", + "example": "First Party" + }, + "expand": { + "type": "boolean", + "required": false, + "description": "Expand form on open.", + "default": true + }, + "minimize": { + "type": "boolean", + "required": false, + "description": "Set to `true` to always minimize form fields. Requires to click on the field to expand the form.", + "default": false + }, + "orderAsOnPage": { + "type": "boolean", + "required": false, + "default": false, + "description": "Order form fields based on their position on the pages." + }, + "externalId": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "logo": { + "type": "string", + "required": false, + "description": "Public logo image URL to use in the signing form." + }, + "language": { + "type": "string", + "required": false, + "description": "UI language: en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja languages are available. Be default the form is displayed in the user browser language automatically." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See submission_form/i18n.js for available i18n keys." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + }, + "goToLast": { + "type": "boolean", + "required": false, + "default": true, + "description": "Navigate to the last unfinished step." + }, + "withFieldNames": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to hide field name. Hidding field names can be useful for when they are not in the human readable format. Field names are displayed by default." + }, + "withFieldPlaceholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "skipFields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow skipping form fields." + }, + "autoscrollFields": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable auto-scrolling to the next document field." + }, + "sendCopyEmail": { + "type": "boolean", + "required": false, + "description": "Set `false` to disable automatic email sending with signed documents to the signers. Emails with signed documents are sent to the signers by default." + }, + "backgroundColor": { + "type": "string", + "required": false, + "description": "Form background color. Only HEX color codes are supported.", + "example": "#d9d9d9" + }, + "completedRedirectUrl": { + "type": "string", + "required": false, + "description": "URL to redirect to after the submission completion.", + "example": "https://docuseal.com/success" + }, + "completedMessage": { + "type": "object", + "required": false, + "description": "Message displayed after the form completion.", + "properties": { + "title": { + "type": "string", + "required": false, + "description": "Message title.", + "example": "Documents have been signed!" + }, + "body": { + "type": "string", + "required": false, + "description": "Message content.", + "example": "If you have any questions, please contact us." + } + } + }, + "completedButton": { + "type": "object", + "required": false, + "description": "Customizable button after form completion.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Button label.", + "example": "Go Back" + }, + "url": { + "type": "string", + "required": true, + "description": "Button link. Only absolute URLs are supported.", + "example": "https://example.com" + } + } + }, + "withTitle": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the document title from the form." + }, + "withDecline": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the decline button in the form." + }, + "withDownloadButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document download button from the completed form card." + }, + "withSendCopyButton": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document send email button from the completed form card." + }, + "withCompleteButton": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the complete button in the form header." + }, + "allowToResubmit": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow user to re-submit the form." + }, + "allowTypedSignature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow users to type their signature." + }, + "signature": { + "type": "string", + "required": false, + "description": "Allows pre-filling signature fields. The value can be a base64 encoded image string, a public URL to an image, or plain text that will be rendered as a typed signature using a standard font." + }, + "rememberSignature": { + "type": "boolean", + "required": false, + "description": "Allows to specify whether the signature should be remembered for future use. Remembered signatures are stored in the signer's browser local storage and can be automatically reused to prefill signature fields in new forms for the signer when the value is set to `true`." + }, + "reuseSignature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to not reuse the signature in the second signature field and collect a new one." + }, + "values": { + "type": "object", + "required": false, + "description": "Pre-assigned values for form fields.", + "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" + }, + "metadata": { + "type": "object", + "required": false, + "description": "Metadata object with additional signer information.", + "example": "{ customData: 'custom value' }" + }, + "readonlyFields": { + "type": "array", + "required": false, + "description": "List of read-only fields.", + "example": "['First Name','Last Name']" + }, + "customCss": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form.", + "example": "#submit_form_button { background-color: #d9d9d9; }" + } +} +``` + +### Callback + +```json +{ + "onInit": { + "type": "function", + "required": false, + "description": "Function to be called on initializing the form component.", + "example": "() => { console.log(\"Loaded\") }" + }, + "onLoad": { + "type": "function", + "required": false, + "description": "Function to be called on loading the form data.", + "example": "(data) => { console.log(data) }" + }, + "onComplete": { + "type": "function", + "required": false, + "description": "Function to be called after the form completion.", + "example": "(data) => { console.log(data) }" + }, + "onDecline": { + "type": "function", + "required": false, + "description": "Function to be called after the form decline.", + "example": "(data) => { console.log(data) }" + } +} +``` diff --git a/docs/embedding/signing-form-vue.md b/docs/embedding/signing-form-vue.md new file mode 100644 index 00000000..afe1c597 --- /dev/null +++ b/docs/embedding/signing-form-vue.md @@ -0,0 +1,302 @@ +# Vue Signing Form + +### Example Code + +```vue + + + + +``` + +### Attributes + +```json +{ + "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.
    • " + }, + "email": { + "type": "string", + "required": false, + "description": "Email address of the signer. Additional email form step will be displayed if the email attribute is not specified." + }, + "name": { + "type": "string", + "required": false, + "description": "Name of the signer." + }, + "role": { + "type": "string", + "required": false, + "description": "The role name or title of the signer.", + "example": "First Party" + }, + "external-id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "expand": { + "type": "boolean", + "required": false, + "description": "Expand form on open.", + "default": true + }, + "minimize": { + "type": "boolean", + "required": false, + "description": "Set to `true` to always minimize form fields. Requires to click on the field to expand the form.", + "default": false + }, + "order-as-on-page": { + "type": "boolean", + "required": false, + "default": false, + "description": "Order form fields based on their position on the pages." + }, + "logo": { + "type": "string", + "required": false, + "description": "Public logo image URL to use in the signing form." + }, + "language": { + "type": "string", + "required": false, + "description": "UI language: en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja languages are available. Be default the form is displayed in the user browser language automatically." + }, + "i18n": { + "type": "object", + "required": false, + "default": "{}", + "description": "Object that contains i18n keys to replace the default UI text with custom values. See submission_form/i18n.js for available i18n keys." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + }, + "go-to-last": { + "type": "boolean", + "required": false, + "default": true, + "description": "Navigate to the last unfinished step." + }, + "skip-fields": { + "type": "boolean", + "required": false, + "default": false, + "description": "Allow skipping form fields." + }, + "autoscroll-fields": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable auto-scrolling to the next document field." + }, + "with-field-names": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to hide field name. Hidding field names can be useful for when they are not in the human readable format. Field names are displayed by default." + }, + "with-field-placeholder": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display field name placeholders instead of the field type icons." + }, + "send-copy-email": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disable automatic email sending with signed documents to the signers. Emails with signed documents are sent to the signers by default." + }, + "background-color": { + "type": "string", + "required": false, + "description": "Form background color. Only HEX color codes are supported.", + "example": "#d9d9d9" + }, + "with-title": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the document title from the form." + }, + "with-decline": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the decline button in the form." + }, + "with-download-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document download button from the completed form card." + }, + "with-send-copy-button": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to remove the signed document send email button from the completed form card." + }, + "with-complete-button": { + "type": "boolean", + "required": false, + "default": false, + "description": "Set `true` to display the complete button in the form header." + }, + "allow-to-resubmit": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow user to re-submit the form." + }, + "signature": { + "type": "string", + "required": false, + "description": "Allows pre-filling signature fields. The value can be a base64 encoded image string, a public URL to an image, or plain text that will be rendered as a typed signature using a standard font." + }, + "remember-signature": { + "type": "boolean", + "required": false, + "description": "Allows to specify whether the signature should be remembered for future use. Remembered signatures are stored in the signer's browser local storage and can be automatically reused to prefill signature fields in new forms for the signer when the value is set to `true`." + }, + "reuse-signature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to not reuse the signature in the second signature field and collect a new one." + }, + "allow-typed-signature": { + "type": "boolean", + "required": false, + "default": true, + "description": "Set `false` to disallow users to type their signature." + }, + "completed-redirect-url": { + "type": "string", + "required": false, + "description": "URL to redirect to after the submission completion.", + "example": "https://docuseal.com/success" + }, + "completed-message": { + "type": "object", + "required": false, + "description": "Message displayed after the form completion.", + "properties": { + "title": { + "type": "string", + "required": false, + "description": "Message title.", + "example": "Documents have been signed!" + }, + "body": { + "type": "string", + "required": false, + "description": "Message content.", + "example": "If you have any questions, please contact us." + } + } + }, + "completed-button": { + "type": "object", + "required": false, + "description": "Customizable button after form completion.", + "properties": { + "title": { + "type": "string", + "required": true, + "description": "Button label.", + "example": "Go Back" + }, + "url": { + "type": "string", + "required": true, + "description": "Button link. Only absolute URLs are supported.", + "example": "https://example.com" + } + } + }, + "values": { + "type": "object", + "required": false, + "description": "Pre-assigned values for form fields.", + "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" + }, + "metadata": { + "type": "object", + "required": false, + "description": "Metadata object with additional signer information.", + "example": "{ customData: 'custom value' }" + }, + "readonly-fields": { + "type": "array", + "required": false, + "description": "List of read-only fields.", + "example": "['First Name','Last Name']" + }, + "custom-css": { + "type": "string", + "required": false, + "description": "Custom CSS styles to be applied to the form.", + "example": "#submit_form_button { background-color: #d9d9d9; }" + } +} +``` + +### Callback + +```json +{ + "@init": { + "type": "function", + "required": false, + "description": "Function to be called on initializing the form component.", + "example": "onFormLoad" + }, + "@load": { + "type": "function", + "required": false, + "description": "Function to be called on loading the form data.", + "example": "onFormLoad" + }, + "@complete": { + "type": "function", + "required": false, + "description": "Function to be called after the form completion.", + "example": "onFormComplete" + }, + "@decline": { + "type": "function", + "required": false, + "description": "Function to be called after the form decline.", + "example": "onFormDecline" + } +} +``` diff --git a/docs/openapi.json b/docs/openapi.json new file mode 100644 index 00000000..93f4dabf --- /dev/null +++ b/docs/openapi.json @@ -0,0 +1,7568 @@ +{ + "openapi": "3.0.0", + "servers": [ + { + "url": "https://api.docuseal.com", + "description": "Global Server" + }, + { + "url": "https://api.docuseal.eu", + "description": "EU Server" + } + ], + "info": { + "version": "1.0.0", + "title": "DocuSeal API", + "description": "DocuSeal API specs", + "contact": { + "name": "DocuSeal", + "email": "admin@docuseal.com", + "url": "https://www.docuseal.com" + } + }, + "components": { + "securitySchemes": { + "AuthToken": { + "type": "apiKey", + "in": "header", + "name": "X-Auth-Token" + } + } + }, + "tags": [ + { + "name": "Submissions", + "description": "Signature requests can be initiated with Submissions API. Submissions can contain one submitter if signed by a single party or multiple submitters if the document template form contains signatures and fields to be collected and filled by multiple parties. Initiate new submissions to request signatures for specified submitters via email or phone number." + }, + { + "name": "Submitters", + "description": "Submitters API allows you to load all details provided by the signer of the document." + }, + { + "name": "Templates", + "description": "Templates represent reusable document signing forms with fields and signatures to be collected. It's possible to create unique template forms with fields and signatures using HTML or with tagged PDFs." + } + ], + "paths": { + "/templates": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "List all templates", + "description": "The API endpoint provides the ability to retrieve a list of available document 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." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "data", + "pagination" + ], + "properties": { + "data": { + "type": "array", + "description": "List of templates.", + "items": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + } + }, + "pagination": { + "type": "object", + "required": [ + "count", + "next", + "prev" + ], + "properties": { + "count": { + "type": "integer", + "description": "Templates count." + }, + "next": { + "type": "integer", + "nullable": true, + "description": "The ID of the tempate after which the next page starts." + }, + "prev": { + "type": "integer", + "nullable": true, + "description": "The ID of the tempate before which the previous page ends." + } + } + } + } + }, + "example": { + "data": [ + { + "id": 1, + "slug": "iRgjDX7WDK6BRo", + "name": "Example Template", + "preferences": {}, + "schema": [ + { + "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "name": "example-document" + } + ], + "fields": [ + { + "uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02", + "submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "name": "Full Name", + "type": "text", + "required": true, + "preferences": {}, + "areas": [ + { + "x": 0.2638888888888889, + "y": 0.168958742632613, + "w": 0.325, + "h": 0.04616895874263263, + "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "page": 0 + } + ] + } + ], + "submitters": [ + { + "name": "First Party", + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:21:57.375Z", + "updated_at": "2023-12-14T15:22:55.094Z", + "source": "native", + "folder_id": 1, + "folder_name": "Default", + "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 5, + "uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "url": "https://docuseal.com/file/hash/sample-document.pdf", + "preview_image_url": "https://docuseal.com/file/hash/0.jpg", + "filename": "example-document.pdf" + } + ] + } + ], + "pagination": { + "count": 1, + "next": 1, + "prev": 2 + } + } + } + } + } + } + } + }, + "/templates/{id}": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Get a template", + "description": "The API endpoint provides the functionality to retrieve information about a document template.", + "operationId": "getTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 1, + "slug": "iRgjDX7WDK6BRo", + "name": "Example Template", + "preferences": {}, + "schema": [ + { + "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "name": "example-document" + } + ], + "fields": [ + { + "uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02", + "submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "name": "Full Name", + "type": "text", + "required": true, + "preferences": {}, + "areas": [ + { + "x": 0.2638888888888889, + "y": 0.168958742632613, + "w": 0.325, + "h": 0.04616895874263263, + "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "page": 0 + } + ] + } + ], + "submitters": [ + { + "name": "First Party", + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:21:57.375Z", + "updated_at": "2023-12-14T15:22:55.094Z", + "source": "native", + "folder_id": 1, + "folder_name": "Default", + "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 5, + "uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", + "url": "https://docuseal.com/file/hash/sample-document.pdf", + "preview_image_url": "https://docuseal.com/file/hash/0.jpg", + "filename": "example-document.pdf" + } + ] + } + } + } + } + } + }, + "delete": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Archive a template", + "description": "The API endpoint allows you to archive a document template.", + "operationId": "archiveTemplate", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the document template.", + "example": 1000001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "archived_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Template unique ID number." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + } + } + }, + "example": { + "id": 1, + "archived_at": "2023-12-14T15:50:21.799Z" + } + } + } + } + } + }, + "put": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update a template", + "description": "The API endpoint provides the functionality to move a document template to a different folder and update the name of the 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." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "updated_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Template unique ID number." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was last updated." + } + } + }, + "example": { + "id": 1, + "updated_at": "2023-12-14T15:50:21.799Z" + } + } + } + } + } + } + }, + "/submissions": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "List all submissions", + "description": "The API endpoint provides the ability to retrieve a list of available 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." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "data", + "pagination" + ], + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "source", + "slug", + "status", + "submitters_order", + "audit_log_url", + "completed_at", + "created_at", + "updated_at", + "submitters", + "template", + "created_by_user" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "source": { + "type": "string", + "description": "The source of the submission.", + "enum": [ + "invite", + "bulk", + "api", + "embed", + "link" + ] + }, + "slug": { + "type": "string", + "description": "Unique slug of the submission." + }, + "status": { + "type": "string", + "description": "The status of the submission.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "submitters_order": { + "type": "string", + "description": "The order of submitters.", + "enum": [ + "random", + "preserved" + ] + }, + "audit_log_url": { + "type": "string", + "nullable": true, + "description": "Audit log file URL." + }, + "combined_document_url": { + "type": "string", + "nullable": true, + "description": "Combined PDF file URL with documents and Audit Log." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submission was completed." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submission was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submission was last updated." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submission was archived." + }, + "submitters": { + "type": "array", + "description": "The list of submitters.", + "items": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "status", + "role", + "metadata", + "preferences" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission ID number." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the form signing link and embedded form." + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined to complete the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "Submitter phone number." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "status": { + "type": "string", + "description": "The status of signing request for the submitter.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "role": { + "type": "string", + "description": "The role of the submitter." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information." + }, + "preferences": { + "type": "object", + "description": "Object with submitter preferences." + } + } + } + }, + "template": { + "type": "object", + "required": [ + "id", + "name", + "external_id", + "folder_name", + "created_at", + "updated_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Template unique ID number." + }, + "name": { + "type": "string", + "description": "The name of the submission template." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this template within your app." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is located." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submission template was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submission template was last updated." + } + } + }, + "created_by_user": { + "type": "object", + "nullable": true, + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the user who created the submission." + }, + "first_name": { + "type": "string", + "description": "The first name of the user who created the submission." + }, + "last_name": { + "type": "string", + "description": "The last name of the user who created the submission." + }, + "email": { + "type": "string", + "description": "The email address of the user who created the submission." + } + } + } + } + } + }, + "pagination": { + "type": "object", + "required": [ + "count", + "next", + "prev" + ], + "properties": { + "count": { + "type": "integer", + "description": "Submissions count." + }, + "next": { + "type": "integer", + "nullable": true, + "description": "The ID of the submission after which the next page starts." + }, + "prev": { + "type": "integer", + "nullable": true, + "description": "The ID of the submission before which the previous page ends." + } + } + } + } + }, + "example": { + "data": [ + { + "id": 1, + "source": "link", + "submitters_order": "random", + "slug": "VyL4szTwYoSvXq", + "status": "completed", + "audit_log_url": "https://docuseal.com/file/hash/example.pdf", + "combined_document_url": null, + "expire_at": null, + "completed_at": "2023-12-10T15:49:21.895Z", + "created_at": "2023-12-10T15:48:17.166Z", + "updated_at": "2023-12-10T15:49:21.895Z", + "archived_at": null, + "submitters": [ + { + "id": 1, + "submission_id": 1, + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "email": "submitter@example.com", + "slug": "dsEeWrhRD8yDXT", + "sent_at": "2023-12-14T15:45:49.011Z", + "opened_at": "2023-12-14T15:48:23.011Z", + "completed_at": "2023-12-14T15:49:21.701Z", + "declined_at": null, + "created_at": "2023-12-10T15:48:17.173Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "John Doe", + "phone": "+1234567890", + "status": "completed", + "role": "First Party", + "metadata": {}, + "preferences": {} + } + ], + "template": { + "id": 1, + "name": "Example Template", + "external_id": "Temp123", + "folder_name": "Default", + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z" + }, + "created_by_user": { + "id": 1, + "first_name": "Bob", + "last_name": "Smith", + "email": "bob.smith@example.com" + } + } + ], + "pagination": { + "count": 1, + "next": 1, + "prev": 1 + } + } + } + } + } + } + }, + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission", + "description": "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", + "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.", + "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." + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject for the submitter." + }, + "body": { + "type": "string", + "description": "Custom signature request email body for the submitter. 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": "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." + }, + "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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" + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "status", + "values", + "metadata", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "external_id", + "preferences", + "role", + "embed_src" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission UUID." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the signing form URL." + }, + "status": { + "type": "string", + "description": "The status of signing request for the submitter.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submission.", + "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." + } + } + } + }, + "metadata": { + "type": "object" + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "The name of the submitter." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "The phone number of the submitter." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "preferences": { + "type": "object", + "properties": { + "send_email": { + "type": "boolean", + "description": "Indicates whether the signature request email should be sent." + }, + "send_sms": { + "type": "boolean", + "description": "Indicates whether the signature request should be sent via SMS." + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + }, + "embed_src": { + "type": "string", + "description": "The `src` URL value to embed the signing form or sign via a link." + } + } + } + }, + "example": [ + { + "id": 1, + "submission_id": 1, + "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", + "email": "john.doe@example.com", + "slug": "pAMimKcyrLjqVt", + "sent_at": "2023-12-13T23:04:04.252Z", + "opened_at": null, + "completed_at": null, + "declined_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "string", + "phone": "+1234567890", + "external_id": "2321", + "metadata": { + "customData": "custom value" + }, + "status": "sent", + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "preferences": { + "send_email": true, + "send_sms": false + }, + "role": "First Party", + "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" + } + ] + } + } + } + } + } + }, + "/submissions/{id}": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get a submission", + "description": "The API endpoint provides the functionality to retrieve information about a submission.", + "operationId": "getSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "source", + "submitters_order", + "audit_log_url", + "combined_document_url", + "created_at", + "updated_at", + "archived_at", + "submitters", + "template", + "created_by_user", + "submission_events", + "documents", + "status", + "metadata", + "completed_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "slug": { + "type": "string", + "description": "Unique slug of the submission." + }, + "source": { + "type": "string", + "description": "The source of the submission.", + "enum": [ + "invite", + "bulk", + "api", + "embed", + "link" + ] + }, + "submitters_order": { + "type": "string", + "description": "The order of submitters.", + "enum": [ + "random", + "preserved" + ] + }, + "audit_log_url": { + "type": "string", + "nullable": true, + "description": "Audit log file URL." + }, + "combined_document_url": { + "type": "string", + "nullable": true, + "description": "Combined PDF file URL with documents and Audit Log." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submission was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submission was last updated." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submission was archived." + }, + "submitters": { + "type": "array", + "description": "The list of submitters.", + "items": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "external_id", + "status", + "values", + "documents", + "role" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the form signing link and embedded form." + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "Submitter phone number." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "status": { + "type": "string", + "description": "The status of signing request for the submitter.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "values": { + "type": "array", + "description": "An array of field 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." + } + } + } + }, + "documents": { + "type": "array", + "description": "An array of completed or signed documents by the submitter.", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + } + } + } + }, + "template": { + "type": "object", + "required": [ + "id", + "name", + "external_id", + "folder_name", + "created_at", + "updated_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Template unique ID number." + }, + "name": { + "type": "string", + "description": "The name of the submission template." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this template within your app." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is located." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submission template was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submission template was last updated." + } + } + }, + "created_by_user": { + "type": "object", + "nullable": true, + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the user who created the submission." + }, + "first_name": { + "type": "string", + "description": "The first name of the user who created the submission." + }, + "last_name": { + "type": "string", + "description": "The last name of the user who created the submission." + }, + "email": { + "type": "string", + "description": "The email address of the user who created the submission." + } + } + }, + "submission_events": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submitter_id", + "event_type", + "event_timestamp" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission event unique ID number." + }, + "submitter_id": { + "type": "integer", + "description": "Unique identifier of the submitter that triggered the event." + }, + "event_type": { + "type": "string", + "description": "Event type.", + "enum": [ + "send_email", + "bounce_email", + "complaint_email", + "send_reminder_email", + "send_sms", + "send_2fa_sms", + "open_email", + "click_email", + "click_sms", + "phone_verified", + "start_form", + "start_verification", + "complete_verification", + "view_form", + "invite_party", + "complete_form", + "decline_form", + "api_complete_form" + ] + }, + "event_timestamp": { + "type": "string", + "description": "Date and time when the event was triggered." + } + } + } + }, + "documents": { + "type": "array", + "description": "An array of completed or signed documents of the submission.", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "status": { + "type": "string", + "description": "The status of the submission.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "metadata": { + "type": "object", + "description": "Object with custom metadata." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submission was fully completed." + } + } + }, + "example": { + "id": 1, + "source": "link", + "submitters_order": "random", + "slug": "VyL4szTwYoSvXq", + "audit_log_url": "https://docuseal.com/blobs/proxy/hash/example.pdf", + "combined_document_url": null, + "completed_at": "2023-12-14T15:49:21.701Z", + "expire_at": null, + "created_at": "2023-12-10T15:48:17.166Z", + "updated_at": "2023-12-10T15:49:21.895Z", + "archived_at": null, + "submitters": [ + { + "id": 1, + "submission_id": 1, + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "email": "submitter@example.com", + "slug": "dsEeWrhRD8yDXT", + "sent_at": "2023-12-14T15:45:49.011Z", + "opened_at": "2023-12-14T15:48:23.011Z", + "completed_at": "2023-12-14T15:49:21.701Z", + "declined_at": null, + "created_at": "2023-12-14T15:48:17.173Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "John Doe", + "phone": "+1234567890", + "external_id": null, + "status": "completed", + "metadata": {}, + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "documents": [ + { + "name": "example", + "url": "https://docuseal.com/blobs/proxy/hash/example.pdf" + } + ], + "role": "First Party" + } + ], + "template": { + "id": 1, + "name": "Example Template", + "external_id": "Temp123", + "folder_name": "Default", + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z" + }, + "created_by_user": { + "id": 1, + "first_name": "Bob", + "last_name": "Smith", + "email": "bob.smith@example.com" + }, + "submission_events": [ + { + "id": 1, + "submitter_id": 2, + "event_type": "view_form", + "event_timestamp": "2023-12-14T15:47:24.566Z" + } + ], + "documents": [ + { + "name": "example", + "url": "https://docuseal.com/file/hash/example.pdf" + } + ], + "status": "completed" + } + } + } + } + } + }, + "delete": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Archive a submission", + "description": "The API endpoint allows you to archive a submission.", + "operationId": "archiveSubmission", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "archived_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the submission was archived." + } + } + }, + "example": { + "id": 1, + "archived_at": "2023-12-14T15:50:21.799Z" + } + } + } + } + } + } + }, + "/submissions/{id}/documents": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Get submission documents", + "description": "This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned.", + "operationId": "getSubmissionDocuments", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submission.", + "example": 1001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + } + } + }, + "example": { + "id": 1, + "documents": [ + { + "name": "example", + "url": "https://docuseal.com/file/hash/example.pdf" + } + ] + } + } + } + } + } + } + }, + "/submissions/emails": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create submissions from emails", + "description": "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.", + "operationId": "createSubmissionsFromEmails", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "template_id", + "emails" + ], + "properties": { + "template_id": { + "type": "integer", + "description": "The unique identifier of the template.", + "example": 1000001 + }, + "emails": { + "type": "string", + "description": "A comma-separated list of email addresses to send the submission to.", + "example": "{{emails}}" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "status", + "values", + "metadata", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "external_id", + "preferences", + "role", + "embed_src" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission UUID." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the signing form URL." + }, + "status": { + "type": "string", + "description": "The status of signing request for the submitter.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submission.", + "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." + } + } + } + }, + "metadata": { + "type": "object" + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "The name of the submitter." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "The phone number of the submitter." + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "preferences": { + "type": "object", + "properties": { + "send_email": { + "type": "boolean", + "description": "Indicates whether the signature request email should be sent." + }, + "send_sms": { + "type": "boolean", + "description": "Indicates whether the signature request should be sent via SMS." + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + }, + "embed_src": { + "type": "string", + "description": "The `src` URL value to embed the signing form or sign via a link." + } + } + } + }, + "example": [ + { + "id": 1, + "submission_id": 1, + "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", + "email": "john.doe@example.com", + "slug": "pAMimKcyrLjqVt", + "sent_at": "2023-12-13T23:04:04.252Z", + "opened_at": null, + "completed_at": null, + "declined_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "string", + "phone": "+1234567890", + "external_id": "2321", + "metadata": { + "customData": "custom value" + }, + "status": "sent", + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "preferences": { + "send_email": true, + "send_sms": false + }, + "role": "First Party", + "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" + }, + { + "id": 2, + "submission_id": 1, + "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", + "email": "alan.smith@example.com", + "slug": "SEwc65vHNDH3QS", + "sent_at": "2023-12-13T23:04:04.252Z", + "opened_at": null, + "completed_at": null, + "declined_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "string", + "phone": "+1234567890", + "external_id": "2321", + "metadata": { + "customData": "custom value" + }, + "status": "sent", + "values": [ + { + "field": "Full Name", + "value": "Roe Moe" + } + ], + "preferences": { + "send_email": true, + "send_sms": false + }, + "role": "First Party", + "embed_src": "SEwc65vHNDH3QS" + } + ] + } + } + } + } + } + }, + "/submitters/{id}": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Get a submitter", + "description": "The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values.", + "operationId": "getSubmitter", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "integer" + }, + "description": "The unique identifier of the submitter.", + "example": 500001 + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "status", + "external_id", + "metadata", + "preferences", + "template", + "submission_events", + "values", + "documents", + "role" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the form signing link and embedded form." + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "Submitter phone number." + }, + "status": { + "type": "string", + "description": "Submitter's submission status.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "The unique applications-specific identifier" + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information." + }, + "preferences": { + "type": "object", + "description": "Submitter preferences." + }, + "template": { + "type": "object", + "required": [ + "id", + "name", + "created_at", + "updated_at" + ], + "description": "Base template details.", + "properties": { + "id": { + "type": "number", + "description": "The template's unique identifier." + }, + "name": { + "type": "string", + "description": "The template's name." + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "submission_events": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submitter_id", + "event_type", + "event_timestamp" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission event unique ID number." + }, + "submitter_id": { + "type": "integer", + "description": "Unique identifier of the submitter that triggered the event." + }, + "event_type": { + "type": "string", + "description": "Event type.", + "enum": [ + "send_email", + "bounce_email", + "complaint_email", + "send_reminder_email", + "send_sms", + "send_2fa_sms", + "open_email", + "click_email", + "click_sms", + "phone_verified", + "start_form", + "start_verification", + "complete_verification", + "view_form", + "invite_party", + "complete_form", + "decline_form", + "api_complete_form" + ] + }, + "event_timestamp": { + "type": "string", + "description": "Date and time when the event was triggered." + } + } + } + }, + "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." + } + } + } + }, + "documents": { + "type": "array", + "description": "An array of completed or signed documents by the submitter.", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + } + } + }, + "example": { + "id": 7, + "submission_id": 3, + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "email": "submitter@example.com", + "slug": "dsEeWrhRD8yDXT", + "sent_at": "2023-12-14T15:45:49.011Z", + "opened_at": "2023-12-14T15:48:23.011Z", + "completed_at": "2023-12-10T15:49:21.701Z", + "declined_at": null, + "created_at": "2023-12-14T15:48:17.173Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "John Doe", + "phone": "+1234567890", + "status": "completed", + "external_id": null, + "metadata": {}, + "preferences": {}, + "template": { + "id": 2, + "name": "Example Template", + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z" + }, + "submission_events": [ + { + "id": 12, + "submitter_id": 7, + "event_type": "view_form", + "event_timestamp": "2023-12-14T15:47:17.351Z" + } + ], + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "documents": [ + { + "name": "sample-document", + "url": "https://docuseal.com/file/hash/sample-document.pdf" + } + ], + "role": "First Party" + } + } + } + } + } + }, + "put": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "Update a submitter", + "description": "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", + "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_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "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\" }" + }, + "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": "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_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}" + }, + "invalid_message": { + "type": "string", + "description": "A custom message to display on pattern validation failure." + }, + "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 + } + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "status", + "external_id", + "metadata", + "preferences", + "values", + "documents", + "role", + "embed_src" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "nullable": true, + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique key to be used in the form signing link and embedded form." + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "Submitter phone number." + }, + "status": { + "type": "string", + "description": "Submitter's submission status.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "The unique applications-specific identifier" + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information." + }, + "preferences": { + "type": "object", + "description": "Submitter preferences." + }, + "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." + } + } + } + }, + "documents": { + "type": "array", + "description": "An array of completed or signed documents by the submitter.", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + }, + "embed_src": { + "type": "string", + "description": "The `src` URL value to embed the signing form or sign via a link." + } + } + }, + "example": { + "id": 1, + "submission_id": 12, + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "email": "submitter@example.com", + "slug": "dsEeWrhRD8yDXT", + "sent_at": "2023-12-14T15:45:49.011Z", + "opened_at": "2023-12-14T15:48:23.011Z", + "completed_at": "2023-12-10T15:49:21.701Z", + "declined_at": null, + "created_at": "2023-12-14T15:48:17.173Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "John Doe", + "phone": "+1234567890", + "status": "completed", + "external_id": null, + "metadata": {}, + "preferences": {}, + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "documents": [], + "role": "First Party", + "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" + } + } + } + } + } + } + }, + "/submitters": { + "get": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submitters" + ], + "summary": "List all submitters", + "description": "The API endpoint provides the ability to retrieve a list of 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." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submission_id", + "uuid", + "email", + "slug", + "sent_at", + "opened_at", + "completed_at", + "declined_at", + "created_at", + "updated_at", + "name", + "phone", + "status", + "external_id", + "preferences", + "metadata", + "submission_events", + "values", + "documents", + "role" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submitter unique ID number." + }, + "submission_id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "uuid": { + "type": "string", + "description": "Submitter UUID." + }, + "email": { + "type": "string", + "description": "The email address of the submitter." + }, + "slug": { + "type": "string", + "description": "Unique slug of the submitter form." + }, + "sent_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "nullable": true, + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "nullable": true, + "description": "Submitter name." + }, + "phone": { + "type": "string", + "nullable": true, + "description": "Submitter phone number." + }, + "status": { + "type": "string", + "description": "Submitter's submission status.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "The unique applications-specific identifier" + }, + "preferences": { + "type": "object", + "description": "Submitter preferences." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information." + }, + "submission_events": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "submitter_id", + "event_type", + "event_timestamp" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the submission event." + }, + "submitter_id": { + "type": "integer", + "description": "Unique identifier of the submitter that triggered the event." + }, + "event_type": { + "type": "string", + "description": "Event type.", + "enum": [ + "send_email", + "bounce_email", + "complaint_email", + "send_reminder_email", + "send_sms", + "send_2fa_sms", + "open_email", + "click_email", + "click_sms", + "phone_verified", + "start_form", + "start_verification", + "complete_verification", + "view_form", + "invite_party", + "complete_form", + "decline_form", + "api_complete_form" + ] + }, + "event_timestamp": { + "type": "string", + "description": "Date and time when the event was triggered." + } + } + } + }, + "values": { + "type": "array", + "description": "An array of pre-filled values for the submission.", + "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." + } + } + } + }, + "documents": { + "type": "array", + "description": "An array of completed or signed documents by the submitter.", + "items": { + "type": "object", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "role": { + "type": "string", + "description": "The role of the submitter in the signing process." + } + } + } + }, + "pagination": { + "type": "object", + "required": [ + "count", + "next", + "prev" + ], + "properties": { + "count": { + "type": "integer", + "description": "Submitters count." + }, + "next": { + "type": "integer", + "nullable": true, + "description": "The ID of the submitter after which the next page starts." + }, + "prev": { + "type": "integer", + "nullable": true, + "description": "The ID of the submitter before which the previous page ends." + } + } + } + } + }, + "example": { + "data": [ + { + "id": 7, + "submission_id": 3, + "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", + "email": "submitter@example.com", + "slug": "dsEeWrhRD8yDXT", + "sent_at": "2023-12-14T15:45:49.011Z", + "opened_at": "2023-12-14T15:48:23.011Z", + "completed_at": "2023-12-14T15:49:21.701Z", + "declined_at": null, + "created_at": "2023-12-14T15:48:17.173Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "name": "John Doe", + "phone": "+1234567890", + "status": "completed", + "external_id": null, + "preferences": {}, + "metadata": {}, + "template": { + "id": 2, + "name": "Example Template", + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z" + }, + "submission_events": [ + { + "id": 12, + "submitter_id": 7, + "event_type": "view_form", + "event_timestamp": "2023-12-14T15:48:17.351Z" + } + ], + "values": [ + { + "field": "Full Name", + "value": "John Doe" + } + ], + "documents": [ + { + "name": "sample-document", + "url": "https://docuseal.com/file/eyJfcmFpbHMiOnsiIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--f9758362acced0f3c86cdffad02800e/sample-document.pdf" + } + ], + "role": "First Party" + } + ], + "pagination": { + "count": 1, + "next": 1, + "prev": 1 + } + } + } + } + } + } + } + }, + "/templates/{id}/documents": { + "put": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Update template documents", + "description": "The API endpoint allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content.", + "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." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 3, + "slug": "ZQpF222rFBv71q", + "name": "Demo Template", + "schema": [ + { + "name": "Demo Template", + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5" + } + ], + "fields": [ + { + "name": "Name", + "required": false, + "type": "text", + "uuid": "a06c49f6-4b20-4442-ac7f-c1040d2cf1ac", + "submitter_uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3", + "areas": [ + { + "page": 0, + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "Submitter", + "uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 1, + "folder_name": "Default", + "external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 3, + "uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "url": "https://docuseal.com/file/hash/Test%20Template.pdf" + } + ] + } + } + } + } + } + } + }, + "/templates/{id}/clone": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Clone a template", + "description": "The API endpoint allows you to clone existing template into a new 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." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 6, + "slug": "Xc7opTqwwV9P7x", + "name": "Cloned Template", + "schema": [ + { + "attachment_uuid": "68aa0716-61f0-4535-9ba4-6c00f835b080", + "name": "sample-document" + } + ], + "fields": [ + { + "uuid": "93c7065b-1b19-4551-b67b-9946bf1c11c9", + "submitter_uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5", + "name": "Name", + "type": "text", + "required": true, + "areas": [ + { + "page": 0, + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "First Party", + "uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 2, + "folder_name": "Default", + "external_id": null, + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 9, + "uuid": "ded62277-9705-4fac-b5dc-58325d4102eb", + "url": "https://docuseal.com/file/hash/sample-document.pdf", + "filename": "sample-document.pdf" + } + ] + } + } + } + } + } + } + }, + "/templates/html": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from HTML", + "description": "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", + "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." + }, + "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" + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 3, + "slug": "ZQpF222rFBv71q", + "name": "Demo Template", + "schema": [ + { + "name": "Demo Template", + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5" + } + ], + "fields": [ + { + "name": "Name", + "required": false, + "type": "text", + "uuid": "a06c49f6-4b20-4442-ac7f-c1040d2cf1ac", + "submitter_uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3", + "areas": [ + { + "page": 0, + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "Submitter", + "uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 1, + "folder_name": "Default", + "external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 3, + "uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "url": "https://docuseal.com/file/hash/Test%20Template.pdf" + } + ] + } + } + } + } + } + } + }, + "/templates/docx": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from Word DOCX", + "description": "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\n", + "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." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "type": "string", + "example": "base64", + "format": "base64", + "description": "Base64-encoded content of the DOCX file or downloadable file URL" + }, + "fields": { + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1." + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "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 + } + } + } + } + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 5, + "slug": "s3ff992CoPjvaX", + "name": "Demo PDF", + "schema": [ + { + "name": "Demo PDF", + "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf" + } + ], + "fields": [ + { + "name": "Name", + "type": "text", + "required": true, + "uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff", + "submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7", + "areas": [ + { + "page": 1, + "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "Submitter", + "uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 1, + "folder_name": "Default", + "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 7, + "uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", + "url": "https://docuseal.com/hash/DemoPDF.pdf" + } + ] + } + } + } + } + } + } + }, + "/templates/pdf": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from existing PDF", + "description": "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\n", + "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" + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
    - Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
    - Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
    - Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the document.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 5, + "slug": "s3ff992CoPjvaX", + "name": "Demo PDF", + "schema": [ + { + "name": "Demo PDF", + "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf" + } + ], + "fields": [ + { + "name": "Name", + "type": "text", + "required": true, + "uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff", + "submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7", + "areas": [ + { + "page": 1, + "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "Submitter", + "uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 1, + "folder_name": "Default", + "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 7, + "uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", + "url": "https://docuseal.com/file/hash/Demo%20PDF.pdf" + } + ] + } + } + } + } + } + } + }, + "/templates/merge": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Merge templates", + "description": "The API endpoint allows you to merge multiple templates with documents and fields into a new combined template.", + "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." + }, + "roles": { + "type": "array", + "description": "An array of submitter role names to be used in the merged template.", + "items": { + "type": "string" + }, + "example": [ + "Agent", + "Customer" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "slug", + "name", + "preferences", + "schema", + "fields", + "submitters", + "author_id", + "archived_at", + "created_at", + "updated_at", + "source", + "external_id", + "folder_id", + "folder_name", + "author", + "documents" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document template." + }, + "slug": { + "type": "string", + "description": "Unique slug of the document template." + }, + "name": { + "type": "string", + "description": "Name of the template." + }, + "preferences": { + "type": "object", + "description": "Template preferences." + }, + "schema": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the template." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the template." + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to be filled in the template.", + "items": { + "type": "object", + "required": [ + "uuid", + "submitter_uuid", + "name", + "type", + "required", + "areas" + ], + "properties": { + "uuid": { + "type": "string", + "description": "Unique identifier of the field." + }, + "submitter_uuid": { + "type": "string", + "description": "Unique identifier of the submitter that filled the field." + }, + "name": { + "type": "string", + "description": "Field 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" + ] + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels." + }, + "font_type": { + "type": "string", + "description": "Font type of the field value." + }, + "font": { + "type": "string", + "description": "Font family of the field value." + }, + "color": { + "type": "string", + "description": "Font color of the field value." + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value." + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value." + }, + "format": { + "type": "string", + "description": "The data format for different field types." + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields." + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields." + }, + "mask": { + "type": "boolean", + "description": "Indicates if the field is masked on the document." + } + } + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "attachment_uuid", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "archived_at": { + "type": "string", + "nullable": true, + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "nullable": true, + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "author": { + "type": "object", + "required": [ + "id", + "first_name", + "last_name", + "email" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "required": [ + "id", + "uuid", + "url", + "preview_image_url", + "filename" + ], + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + }, + "example": { + "id": 6, + "slug": "Xc7opTqwwV9P7x", + "name": "Merged Template", + "schema": [ + { + "attachment_uuid": "68aa0716-61f0-4535-9ba4-6c00f835b080", + "name": "sample-document" + } + ], + "fields": [ + { + "uuid": "93c7065b-1b19-4551-b67b-9946bf1c11c9", + "submitter_uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5", + "name": "Name", + "type": "text", + "required": true, + "areas": [ + { + "page": 0, + "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", + "x": 0.403158189124654, + "y": 0.04211750189825361, + "w": 0.100684625476058, + "h": 0.01423690205011389 + } + ] + } + ], + "submitters": [ + { + "name": "First Party", + "uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5" + } + ], + "author_id": 1, + "archived_at": null, + "created_at": "2023-12-14T15:50:21.799Z", + "updated_at": "2023-12-14T15:50:21.799Z", + "source": "api", + "folder_id": 2, + "folder_name": "Default", + "external_id": null, + "author": { + "id": 1, + "first_name": "John", + "last_name": "Doe", + "email": "john.doe@example.com" + }, + "documents": [ + { + "id": 9, + "uuid": "ded62277-9705-4fac-b5dc-58325d4102eb", + "url": "https://docuseal.com/file/hash/sample-document.pdf", + "filename": "sample-document.pdf" + } + ] + } + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/webhooks/form-webhook.md b/docs/webhooks/form-webhook.md new file mode 100644 index 00000000..439eb924 --- /dev/null +++ b/docs/webhooks/form-webhook.md @@ -0,0 +1,247 @@ +# Form Webhook + +During the form filling and signing process, 3 types of events may occur and are dispatched at different stages: + +- **'form.viewed'** event is triggered when the submitter first opens the form. +- **'form.started'** event is triggered when the submitter initiates filling out the form. +- **'form.completed'** event is triggered upon successful form completion and signing by one of the parties. +- **'form.declined'** event is triggered when a signer declines the submission. + + It's important to note that each of these events contain information available at the time of dispatch, so some data may be missing or incomplete depending on the specific event. Failed webhook requests (4xx, 5xx) are automatically retried multiple times within 48 hours (every 2^attempt minutes) for all production accounts. +**Related Guides** +[Download Signed Documents](https://www.docuseal.com/guides/download-signed-documents) + +```json +{ + "event_type": { + "type": "string", + "description": "The event type.", + "enum": [ + "form.viewed", + "form.started", + "form.completed" + ] + }, + "timestamp": { + "type": "string", + "description": "The event timestamp.", + "example": "2023-09-24T11:20:42Z", + "format": "date-time" + }, + "data": { + "type": "object", + "description": "Submitted data object.", + "properties": { + "id": { + "type": "number", + "description": "The submitter's unique identifier." + }, + "submission_id": { + "type": "number", + "description": "The unique submission identifier." + }, + "email": { + "type": "string", + "description": "The submitter's email address", + "format": "email", + "example": "john.doe@example.com" + }, + "ua": { + "type": "string", + "description": "The user agent string that provides information about the submitter's web browser.", + "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36" + }, + "ip": { + "type": "string", + "description": "The submitter's IP address." + }, + "name": { + "type": "string", + "description": "The submitter's name." + }, + "phone": { + "type": "string", + "description": "The submitter's phone number, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "role": { + "type": "string", + "description": "The submitter's role name or title.", + "example": "First Party" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify submitter within your app." + }, + "application_key": { + "type": "string", + "description": "Your application-specific unique string key to identify submitter within your app. Backward compatibility with the previous version of the API. Use external_id instead." + }, + "decline_reason": { + "type": "string", + "description": "Submitter provided decline message." + }, + "sent_at": { + "type": "string", + "format": "date-time" + }, + "status": { + "type": "string", + "description": "The submitter status.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "opened_at": { + "type": "string", + "format": "date-time" + }, + "completed_at": { + "type": "string", + "format": "date-time" + }, + "declined_at": { + "type": "string", + "format": "date-time" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "submission": { + "type": "object", + "description": "The submission details.", + "properties": { + "id": { + "type": "number", + "description": "The submission's unique identifier." + }, + "audit_log_url": { + "type": "string", + "description": "The audit log PDF URL. Available only if the submission was completed by all submitters." + }, + "combined_document_url": { + "type": "string", + "description": "The URL of the combined documents with audit log. Combined documents can be enabled via /settings/accounts." + }, + "status": { + "type": "string", + "description": "The submission status.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "url": { + "type": "string", + "description": "The submission URL." + }, + "created_at": { + "type": "string", + "description": "The submission creation date.", + "format": "date-time" + } + } + }, + "template": { + "type": "object", + "description": "Base template details.", + "properties": { + "id": { + "type": "number", + "description": "The template's unique identifier." + }, + "name": { + "type": "string", + "description": "The template's name." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify template within your app." + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "folder_name": { + "type": "string", + "description": "Template folder name." + } + } + }, + "preferences": { + "type": "object", + "properties": { + "send_email": { + "type": "boolean", + "description": "The flag indicating whether the submitter has opted to receive an email." + }, + "send_sms": { + "type": "boolean", + "description": "The flag indicating whether the submitter has opted to receive an SMS." + } + } + }, + "values": { + "type": "array", + "description": "List of the filled values passed by the submitter.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "description": "The field name." + }, + "values": { + "type": "string", + "description": "The field value." + } + } + } + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information." + }, + "audit_log_url": { + "type": "string", + "description": "The audit log PDF URL. Available only if the submission was completed by all submitters." + }, + "submission_url": { + "type": "string", + "description": "The submission URL." + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The document file name." + }, + "url": { + "type": "string", + "description": "The document file URL." + } + } + } + } + } + } +} +``` \ No newline at end of file diff --git a/docs/webhooks/submission-webhook.md b/docs/webhooks/submission-webhook.md new file mode 100644 index 00000000..0ebf659c --- /dev/null +++ b/docs/webhooks/submission-webhook.md @@ -0,0 +1,317 @@ +# Submission Webhook + +Get submission creation, completion, expiration, and archiving notifications using these events: + +- **'submission.created'** event is triggered when the submission is created. +- **'submission.completed'** event is triggered when the submission is completed by all signing parties. +- **'submission.expired'** event is triggered when the submission expires. +- **'submission.archived'** event is triggered when the submission is archived. + + + +```json +{ + "event_type": { + "type": "string", + "description": "The event type.", + "enum": [ + "submission.created", + "submission.archived" + ] + }, + "timestamp": { + "type": "string", + "description": "The event timestamp.", + "example": "2023-09-24T11:20:42Z", + "format": "date-time" + }, + "data": { + "type": "object", + "description": "Submitted data object.", + "properties": { + "id": { + "type": "number", + "description": "The submission's unique identifier." + }, + "archived_at": { + "type": "string", + "description": "The submission archive date." + }, + "created_at": { + "type": "string", + "description": "The submission creation date." + }, + "updated_at": { + "type": "string", + "description": "The submission update date." + }, + "source": { + "type": "string", + "description": "The submission source.", + "enum": [ + "invite", + "bulk", + "api", + "embed", + "link" + ] + }, + "submitters_order": { + "type": "string", + "description": "The submitters order.", + "enum": [ + "random", + "preserved" + ] + }, + "audit_log_url": { + "type": "string", + "description": "Audit log file URL." + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The submitter's unique identifier." + }, + "submission_id": { + "type": "number", + "description": "The unique submission identifier." + }, + "uuid": { + "type": "string", + "description": "The submitter UUID." + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "slug": { + "type": "string", + "description": "The unique slug of the document template." + }, + "sent_at": { + "type": "string", + "description": "The date and time when the signing request was sent to the submitter." + }, + "opened_at": { + "type": "string", + "description": "The date and time when the submitter opened the signing form." + }, + "completed_at": { + "type": "string", + "description": "The date and time when the submitter completed the signing form." + }, + "declined_at": { + "type": "string", + "description": "The date and time when the submitter declined the signing form." + }, + "created_at": { + "type": "string", + "description": "The date and time when the submitter was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the submitter was last updated." + }, + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ 'customField': 'value' }" + }, + "status": { + "type": "string", + "description": "The submitter status.", + "enum": [ + "completed", + "declined", + "opened", + "sent", + "awaiting" + ] + }, + "application_key": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "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." + }, + "documents": { + "type": "array", + "description": "The list of documents for the submission.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The document file name." + }, + "url": { + "type": "string", + "description": "The document file URL." + } + } + } + }, + "preferences": { + "type": "object", + "description": "The submitter preferences." + } + } + } + }, + "template": { + "type": "object", + "description": "Base template details.", + "properties": { + "id": { + "type": "number", + "description": "The template's unique identifier." + }, + "name": { + "type": "string", + "description": "The template's name." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify template within your app." + }, + "folder_name": { + "type": "string", + "description": "The folder name." + }, + "created_at": { + "type": "string", + "description": "The date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "The date and time when the template was last updated." + } + } + }, + "created_by_user": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the user who created the submission." + }, + "first_name": { + "type": "string", + "description": "The first name of the user who created the submission." + }, + "last_name": { + "type": "string", + "description": "The last name of the user who created the submission." + }, + "email": { + "type": "string", + "description": "The email address of the user who created the submission." + } + } + }, + "submission_events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Submission event unique ID number." + }, + "submitter_id": { + "type": "integer", + "description": "Unique identifier of the submitter that triggered the event." + }, + "event_type": { + "type": "string", + "description": "Event type.", + "enum": [ + "send_email", + "bounce_email", + "complaint_email", + "send_reminder_email", + "send_sms", + "send_2fa_sms", + "open_email", + "click_email", + "click_sms", + "phone_verified", + "start_form", + "start_verification", + "complete_verification", + "view_form", + "invite_party", + "complete_form", + "decline_form", + "api_complete_form" + ] + }, + "event_timestamp": { + "type": "string", + "description": "Date and time when the event was triggered." + } + } + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "url": { + "type": "string", + "description": "Document URL." + } + } + } + }, + "status": { + "type": "string", + "description": "The status of the submission.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "completed_at": { + "type": "string", + "description": "The date and time when the submission was fully completed." + } + } + } +} +``` \ No newline at end of file diff --git a/docs/webhooks/template-webhook.md b/docs/webhooks/template-webhook.md new file mode 100644 index 00000000..b843a0ed --- /dev/null +++ b/docs/webhooks/template-webhook.md @@ -0,0 +1,235 @@ +# Template Webhook + +Get template creation and update notifications using these events: + +- **'template.created'** is triggered when the template is created. +- **'tempate.updated'** is triggered when the template is updated. + + + +```json +{ + "event_type": { + "type": "string", + "description": "The event type.", + "enum": [ + "template.created", + "template.updated" + ] + }, + "timestamp": { + "type": "string", + "description": "The event timestamp.", + "example": "2023-09-24T11:20:42Z", + "format": "date-time" + }, + "data": { + "type": "object", + "description": "Submitted data object.", + "properties": { + "id": { + "type": "number", + "description": "The template's unique identifier." + }, + "slug": { + "type": "string", + "description": "The template's unique slug." + }, + "name": { + "type": "string", + "description": "The template's name." + }, + "schema": { + "type": "array", + "description": "The template document files.", + "items": { + "type": "object", + "properties": { + "attachment_uuid": { + "type": "string", + "description": "The attachment UUID." + }, + "name": { + "type": "string", + "description": "The attachment name." + } + } + } + }, + "fields": { + "type": "array", + "description": "The template fields.", + "items": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "description": "The field UUID." + }, + "submitter_uuid": { + "type": "string", + "description": "The submitter role UUID." + }, + "name": { + "type": "string", + "description": "The field name." + }, + "required": { + "type": "boolean", + "description": "The flag indicating whether the field is required." + }, + "preferences": { + "type": "object", + "description": "The field preferences." + }, + "areas": { + "type": "array", + "description": "List of areas where the field is located in the document.", + "items": { + "type": "object", + "properties": { + "x": { + "type": "number", + "description": "X coordinate of the area where the field is located in the document." + }, + "y": { + "type": "number", + "description": "Y coordinate of the area where the field is located in the document." + }, + "w": { + "type": "number", + "description": "Width of the area where the field is located in the document." + }, + "h": { + "type": "number", + "description": "Height of the area where the field is located in the document." + }, + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." + }, + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." + } + } + } + } + } + } + }, + "submitters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Submitter name." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the submitter." + } + } + } + }, + "author_id": { + "type": "integer", + "description": "Unique identifier of the author of the template." + }, + "account_id": { + "type": "integer", + "description": "Unique identifier of the account of the template." + }, + "archived_at": { + "type": "string", + "description": "Date and time when the template was archived." + }, + "created_at": { + "type": "string", + "description": "Date and time when the template was created." + }, + "updated_at": { + "type": "string", + "description": "Date and time when the template was updated." + }, + "source": { + "type": "string", + "description": "Source of the template.", + "enum": [ + "native", + "api", + "embed" + ] + }, + "external_id": { + "type": "string", + "description": "Identifier of the template in the external system." + }, + "folder_id": { + "type": "integer", + "description": "Unique identifier of the folder where the template is placed." + }, + "folder_name": { + "type": "string", + "description": "Folder name where the template is placed." + }, + "application_key": { + "type": "string", + "description": "Your application-specific unique string key to identify tempate_id within your app." + }, + "author": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the author." + }, + "first_name": { + "type": "string", + "description": "First name of the author." + }, + "last_name": { + "type": "string", + "description": "Last name of the author." + }, + "email": { + "type": "string", + "description": "Author email." + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the template.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier of the document." + }, + "uuid": { + "type": "string", + "description": "Unique identifier of the document." + }, + "url": { + "type": "string", + "description": "URL of the document." + }, + "preview_image_url": { + "type": "string", + "description": "Document preview image URL." + }, + "filename": { + "type": "string", + "description": "Document filename." + } + } + } + } + } + } +} +``` \ No newline at end of file