From 894d98e92b16c657f5b020c45c4869eaf9010be8 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Mon, 23 Jun 2025 13:33:44 +0300 Subject: [PATCH 01/27] update widget version --- package.json | 2 +- yarn.lock | 28 ++++++++++++++-------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/package.json b/package.json index b0c4ece8..a65611f2 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "@babel/plugin-transform-runtime": "7.21.4", "@babel/preset-env": "7.21.5", "@babel/runtime": "7.21.5", - "@eid-easy/eideasy-widget": "^2.132.1", + "@eid-easy/eideasy-widget": "^2.159.0", "@github/catalyst": "^2.0.0-beta", "@hotwired/turbo": "https://github.com/docusealco/turbo#main", "@hotwired/turbo-rails": "^7.3.0", diff --git a/yarn.lock b/yarn.lock index 8051ab58..75a1d1b2 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1035,22 +1035,22 @@ resolved "https://registry.yarnpkg.com/@discoveryjs/json-ext/-/json-ext-0.5.7.tgz#1d572bfbbe14b7704e0ba0f39b74815b84870d70" integrity sha512-dBVuXR082gk3jsFp7Rd/JI4kytwGHecnCoTtXFb7DB6CNHp4rg5k1bhg0nWdLGLnOV71lmDzGQaLMy8iPLY0pw== -"@eid-easy/eideasy-browser-client@2.104.1": - version "2.104.1" - resolved "https://registry.yarnpkg.com/@eid-easy/eideasy-browser-client/-/eideasy-browser-client-2.104.1.tgz#e492e0fc8ef1ff470c66522d530d5636264f30b3" - integrity sha512-d4fgqF5U+pWuPpfgbb/+BxI2CYThkbviAfl9NbLoKMOMO4bh7HZFxLdW5uU2O8yIeldGFunJWxEbMTLv/2PlTA== +"@eid-easy/eideasy-browser-client@2.124.0": + version "2.124.0" + resolved "https://registry.yarnpkg.com/@eid-easy/eideasy-browser-client/-/eideasy-browser-client-2.124.0.tgz#940ccb9d4d853f0bd32e49cc455f2c7b13f3bbd1" + integrity sha512-hZuUeg0CcyvgJSseRBQixRStAIr58bulmNcikcASBo6z8wv+/R8nAnUoE7qdNW1l4ZyYxLmVOwDs6+W+FHy6hQ== dependencies: - axios "1.7.8" + axios "1.8.2" jsencrypt "3.2.1" lodash "^4.17.21" serialize-error "^9.1.1" -"@eid-easy/eideasy-widget@^2.132.1": - version "2.132.1" - resolved "https://registry.yarnpkg.com/@eid-easy/eideasy-widget/-/eideasy-widget-2.132.1.tgz#634c077c55d7e582846dbeae47f6f37796b76bd6" - integrity sha512-bZNdKsxja4iIUm6B4x6pOyiBdoMNNUB3615oJgNUWallrfeiIbBQxLwG+m5nmivmHMgdaIQylmtfrhc6e7kgYA== +"@eid-easy/eideasy-widget@^2.159.0": + version "2.159.0" + resolved "https://registry.yarnpkg.com/@eid-easy/eideasy-widget/-/eideasy-widget-2.159.0.tgz#f2291dad292bd5f7941496f0db0aa0a180226b6b" + integrity sha512-527uCNrN5MVY/PaOUoZ3J2XZ0C+xt6057sJ4xSO0/FPYj2cxOn+qyCJODQjOhjBL7GcnpShWPpYAfv1OIStYwQ== dependencies: - "@eid-easy/eideasy-browser-client" "2.104.1" + "@eid-easy/eideasy-browser-client" "2.124.0" core-js "^3.8.3" i18n-iso-countries "^6.7.0" lodash.defaultsdeep "^4.6.1" @@ -1914,10 +1914,10 @@ available-typed-arrays@^1.0.5: resolved "https://registry.yarnpkg.com/available-typed-arrays/-/available-typed-arrays-1.0.5.tgz#92f95616501069d07d10edb2fc37d3e1c65123b7" integrity sha512-DMD0KiN46eipeziST1LPP/STfDU0sufISXmjSgvVsoU2tqxctQeASejWcfNtxYKqETM1UxQ8sp2OrSBWpHY6sw== -axios@1.7.8: - version "1.7.8" - resolved "https://registry.yarnpkg.com/axios/-/axios-1.7.8.tgz#1997b1496b394c21953e68c14aaa51b7b5de3d6e" - integrity sha512-Uu0wb7KNqK2t5K+YQyVCLM76prD5sRFjKHbJYCP1J7JFGEQ6nN7HWn9+04LAeiJ3ji54lgS/gZCH1oxyrf1SPw== +axios@1.8.2: + version "1.8.2" + resolved "https://registry.yarnpkg.com/axios/-/axios-1.8.2.tgz#fabe06e241dfe83071d4edfbcaa7b1c3a40f7979" + integrity sha512-ls4GYBm5aig9vWx8AWDSGLpnpDQRtWAfrjU+EuytuODrFBkqesN2RkOQCBzrA1RQNHw1SmRMSDDDSwzNAYQ6Rg== dependencies: follow-redirects "^1.15.6" form-data "^4.0.0" From 48e73c2c81da34d9a7521aef5fec524df6ef125b Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Mon, 23 Jun 2025 14:53:35 +0300 Subject: [PATCH 02/27] fix png quality --- lib/templates/process_document.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/templates/process_document.rb b/lib/templates/process_document.rb index 77aeaacd..9d6b78db 100644 --- a/lib/templates/process_document.rb +++ b/lib/templates/process_document.rb @@ -69,7 +69,7 @@ module Templates bitdepth = 2**image.stats.to_a[1..3].pluck(2).uniq.size io = StringIO.new(image.write_to_buffer(FORMAT, compression: 7, filter: 0, bitdepth:, - palette: true, Q: bitdepth == 8 ? Q : 5, dither: 0)) + palette: true, Q: Q, dither: 0)) ActiveStorage::Attachment.create!( blob: ActiveStorage::Blob.create_and_upload!( @@ -141,7 +141,7 @@ module Templates bitdepth = 2**page.stats.to_a[1..3].pluck(2).uniq.size page.write_to_buffer(format, compression: 7, filter: 0, bitdepth:, - palette: true, Q: bitdepth == 8 ? Q : 5, dither: 0) + palette: true, Q: Q, dither: 0) else page.write_to_buffer(format, interlace: true, Q: JPEG_Q) end From 33b14d5278e635a5fd6a5d9e3acf9ad37665e7e3 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Mon, 23 Jun 2025 20:34:30 +0300 Subject: [PATCH 03/27] fix sqlite query --- app/controllers/templates_dashboard_controller.rb | 6 ++---- lib/abilities/template_conditions.rb | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/app/controllers/templates_dashboard_controller.rb b/app/controllers/templates_dashboard_controller.rb index 51922c48..69843d15 100644 --- a/app/controllers/templates_dashboard_controller.rb +++ b/app/controllers/templates_dashboard_controller.rb @@ -55,10 +55,8 @@ class TemplatesDashboardController < ApplicationController rel = Template.where( Template.arel_table[:id].in( - Arel::Nodes::Union.new( - rel.where(folder_id: current_account.default_template_folder.id).select(:id).arel, - shared_template_ids.arel - ) + rel.where(folder_id: current_account.default_template_folder.id).select(:id).arel + .union(shared_template_ids.arel) ) ) else diff --git a/lib/abilities/template_conditions.rb b/lib/abilities/template_conditions.rb index 32afd8a3..ac50f3aa 100644 --- a/lib/abilities/template_conditions.rb +++ b/lib/abilities/template_conditions.rb @@ -13,7 +13,7 @@ module Abilities TemplateSharing.where({ ability:, account_id: [user.account_id, TemplateSharing::ALL_ID] }.compact) .select(:template_id) - Template.where(Template.arel_table[:id].in(Arel::Nodes::Union.new(templates.select(:id).arel, shared_ids.arel))) + Template.where(Template.arel_table[:id].in(templates.select(:id).arel.union(shared_ids.arel))) end def entity(template, user:, ability: nil) From ade5c4832f2882c4babd0977b56fcf041a4759d5 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Tue, 24 Jun 2025 12:49:52 +0300 Subject: [PATCH 04/27] fix bulk table mappings --- app/javascript/template_builder/import_list.vue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/javascript/template_builder/import_list.vue b/app/javascript/template_builder/import_list.vue index eeec5185..d5f00711 100644 --- a/app/javascript/template_builder/import_list.vue +++ b/app/javascript/template_builder/import_list.vue @@ -406,7 +406,7 @@ export default { this.mappings.every((m) => m.column_index !== index) }) - if (columnIndex !== -1) { + if (columnIndex !== -1 && this.rows.some((row) => row[columnIndex])) { this.mappings.push({ uuid: v4(), field_name: field.name, column_index: columnIndex, submitter_uuid: submitter.uuid }) } }) From e130584fec6eacaf3f6a16abbad54eaf0f0b08e8 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Wed, 25 Jun 2025 09:38:52 +0300 Subject: [PATCH 05/27] fix timezone selector --- app/views/accounts/show.html.erb | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/app/views/accounts/show.html.erb b/app/views/accounts/show.html.erb index 7f371b9d..658ab7c6 100644 --- a/app/views/accounts/show.html.erb +++ b/app/views/accounts/show.html.erb @@ -14,7 +14,10 @@
<%= ff.label :timezone, t('time_zone'), class: 'label' %> <%= ff.select :timezone, nil, {}, class: 'base-select' do %> - <%= time_zone_options_for_select(current_account.timezone) %> + <% tzinfo = TZInfo::Timezone.get(ActiveSupport::TimeZone::MAPPING[current_account.timezone] || current_account.timezone) %> + <% items = ActiveSupport::TimeZone.all.map { |z| [z.to_s, z.name] } %> + <% items.unshift(tzinfo) unless ActiveSupport::TimeZone.all.find { |e| e.tzinfo == tzinfo } %> + <%= options_for_select(items, current_account.timezone) %> <% end %>
From dee5fc7c07c1e7dd2130c7ff34b8451fec4cb78e Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Wed, 25 Jun 2025 16:34:25 +0300 Subject: [PATCH 06/27] fix preview --- app/views/submissions/show.html.erb | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/app/views/submissions/show.html.erb b/app/views/submissions/show.html.erb index ded86629..33f507ac 100644 --- a/app/views/submissions/show.html.erb +++ b/app/views/submissions/show.html.erb @@ -74,12 +74,14 @@ <% schema = Submissions.filtered_conditions_schema(@submission, values:) %> <% schema.each do |item| %> <% document = @submission.schema_documents.find { |a| item['attachment_uuid'] == a.uuid } %> - " onclick="[event.preventDefault(), window[event.target.closest('a').href.split('#')[1]].scrollIntoView({ behavior: 'smooth', block: 'start' })]" class="block cursor-pointer"> - -
- <%= item['name'].presence || document.filename.base %> -
- + <% if document.preview_images.first %> + " onclick="[event.preventDefault(), window[event.target.closest('a').href.split('#')[1]].scrollIntoView({ behavior: 'smooth', block: 'start' })]" class="block cursor-pointer"> + +
+ <%= item['name'].presence || document.filename.base %> +
+ + <% end %> <% end %>
@@ -92,7 +94,7 @@ <% document = @submission.schema_documents.find { |e| e.uuid == item['attachment_uuid'] } %> <% document_annots_index = document.metadata.dig('pdf', 'annotations')&.group_by { |e| e['page'] } || {} %> <% preview_images_index = document.preview_images.loaded? ? document.preview_images.index_by { |e| e.filename.base.to_i } : {} %> - <% lazyload_metadata = document.preview_images.first.metadata %> + <% lazyload_metadata = document.preview_images.first&.metadata || {} %> <% (document.metadata.dig('pdf', 'number_of_pages') || (document.preview_images.loaded? ? preview_images_index.size : document.preview_images.size)).times do |index| %> <% page = preview_images_index[index] || page_blob_struct.new(metadata: lazyload_metadata, url: preview_document_page_path(document.signed_uuid, "#{index}.jpg")) %>
" class="relative"> From 2e487ac936a5a7116deab27cd2cd3c9bf342f401 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Wed, 25 Jun 2025 21:36:03 +0300 Subject: [PATCH 07/27] fix timezone selector --- app/views/accounts/show.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/accounts/show.html.erb b/app/views/accounts/show.html.erb index 658ab7c6..ac63ff87 100644 --- a/app/views/accounts/show.html.erb +++ b/app/views/accounts/show.html.erb @@ -16,7 +16,7 @@ <%= ff.select :timezone, nil, {}, class: 'base-select' do %> <% tzinfo = TZInfo::Timezone.get(ActiveSupport::TimeZone::MAPPING[current_account.timezone] || current_account.timezone) %> <% items = ActiveSupport::TimeZone.all.map { |z| [z.to_s, z.name] } %> - <% items.unshift(tzinfo) unless ActiveSupport::TimeZone.all.find { |e| e.tzinfo == tzinfo } %> + <% items.unshift([tzinfo.to_s, current_account.timezone]) unless ActiveSupport::TimeZone.all.find { |e| e.tzinfo == tzinfo } %> <%= options_for_select(items, current_account.timezone) %> <% end %>
From ee4acd5a8274494b4908fe1ec96bd84ca8f78d1f Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Wed, 25 Jun 2025 22:31:19 +0300 Subject: [PATCH 08/27] validate signature image --- lib/image_utils.rb | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 lib/image_utils.rb diff --git a/lib/image_utils.rb b/lib/image_utils.rb new file mode 100644 index 00000000..18f99ad5 --- /dev/null +++ b/lib/image_utils.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +module ImageUtils + module_function + + def blank?(image) + min = (0...image.bands).map { |i| image.stats.getpoint(0, i)[0] } + max = (0...image.bands).map { |i| image.stats.getpoint(1, i)[0] } + + return true if min.all?(255) && max.all?(255) + return true if min.all?(0) && max.all?(0) + return true if min.length >= 4 && min[-1].zero? && max[-1].zero? + + false + end +end From 2020f6c136281eb0b0d8e89db57b1ff1d585b1fe Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 07:47:29 +0300 Subject: [PATCH 09/27] make shared templates searchable --- lib/submissions.rb | 3 ++- lib/templates.rb | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/submissions.rb b/lib/submissions.rb index 0fb3b0e0..e8085169 100644 --- a/lib/submissions.rb +++ b/lib/submissions.rb @@ -50,7 +50,8 @@ module Submissions arel, Submission.where( template_id: SearchEntry.where(record_type: 'Template') - .where(account_id: current_user.account_id) + .where(account_id: [current_user.account_id, + current_user.account.linked_account_account&.account_id].compact) .where(*SearchEntries.build_tsquery(keyword)) .select(:record_id) ).select(:id).arel diff --git a/lib/templates.rb b/lib/templates.rb index 95033f02..e1dbdf33 100644 --- a/lib/templates.rb +++ b/lib/templates.rb @@ -56,7 +56,8 @@ module Templates templates.where( id: SearchEntry.where(record_type: 'Template') - .where(account_id: current_user.account_id) + .where(account_id: [current_user.account_id, + current_user.account.linked_account_account&.account_id].compact) .where(*SearchEntries.build_tsquery(keyword)) .select(:record_id) ) From 6ebbc3edac5deee39df34ea0fcb38499ae180070 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 09:02:07 +0300 Subject: [PATCH 10/27] pdfium read text --- lib/pdfium.rb | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/lib/pdfium.rb b/lib/pdfium.rb index 54f22fe4..317dddf0 100644 --- a/lib/pdfium.rb +++ b/lib/pdfium.rb @@ -24,6 +24,7 @@ class Pdfium typedef :pointer, :FPDF_PAGE typedef :pointer, :FPDF_BITMAP typedef :pointer, :FPDF_FORMHANDLE + typedef :pointer, :FPDF_TEXTPAGE MAX_SIZE = 32_767 @@ -72,6 +73,11 @@ class Pdfium attach_function :FPDF_RenderPageBitmap, %i[FPDF_BITMAP FPDF_PAGE int int int int int int], :void + attach_function :FPDFText_LoadPage, [:FPDF_PAGE], :FPDF_TEXTPAGE + attach_function :FPDFText_ClosePage, [:FPDF_TEXTPAGE], :void + attach_function :FPDFText_CountChars, [:FPDF_TEXTPAGE], :int + attach_function :FPDFText_GetText, %i[FPDF_TEXTPAGE int int pointer], :int + typedef :int, :FPDF_BOOL typedef :pointer, :IPDF_JSPLATFORM @@ -346,6 +352,40 @@ class Pdfium Pdfium.FPDFBitmap_Destroy(bitmap_ptr) if bitmap_ptr && !bitmap_ptr.null? end + def text + return @text if @text + + ensure_not_closed! + + text_page = Pdfium.FPDFText_LoadPage(page_ptr) + + if text_page.null? + Pdfium.check_last_error("Failed to load text page #{page_index}") + + raise PdfiumError, "Failed to load text page #{page_index}, pointer is NULL." + end + + char_count = Pdfium.FPDFText_CountChars(text_page) + + return @text = '' if char_count.zero? + + buffer_char_capacity = char_count + 1 + + buffer = FFI::MemoryPointer.new(:uint16, buffer_char_capacity) + + chars_written = Pdfium.FPDFText_GetText(text_page, 0, buffer_char_capacity, buffer) + + if chars_written <= 0 + Pdfium.check_last_error("Failed to extract text from page #{page_index}") + + return @text = '' + end + + @text = buffer.read_bytes((chars_written * 2) - 2).force_encoding('UTF-16LE').encode('UTF-8') + ensure + Pdfium.FPDFText_ClosePage(text_page) if text_page && !text_page.null? + end + def close return if closed? From de5acd0949988115c0b0253191e95fa847d0ac45 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 10:05:16 +0300 Subject: [PATCH 11/27] fix one-off --- app/controllers/submit_form_draw_signature_controller.rb | 2 +- app/controllers/submit_form_invite_controller.rb | 2 +- app/controllers/submit_form_values_controller.rb | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/app/controllers/submit_form_draw_signature_controller.rb b/app/controllers/submit_form_draw_signature_controller.rb index f8352ade..773eb9e7 100644 --- a/app/controllers/submit_form_draw_signature_controller.rb +++ b/app/controllers/submit_form_draw_signature_controller.rb @@ -12,7 +12,7 @@ class SubmitFormDrawSignatureController < ApplicationController return redirect_to submit_form_completed_path(@submitter.slug) if @submitter.completed_at? - if @submitter.submission.template.archived_at? || @submitter.submission.archived_at? + if @submitter.submission.template&.archived_at? || @submitter.submission.archived_at? return redirect_to submit_form_path(@submitter.slug) end diff --git a/app/controllers/submit_form_invite_controller.rb b/app/controllers/submit_form_invite_controller.rb index 1d42779c..0f400ad9 100644 --- a/app/controllers/submit_form_invite_controller.rb +++ b/app/controllers/submit_form_invite_controller.rb @@ -45,7 +45,7 @@ class SubmitFormInviteController < ApplicationController !submitter.completed_at? && !submitter.submission.archived_at? && !submitter.submission.expired? && - !submitter.submission.template.archived_at? + !submitter.submission.template&.archived_at? end def filter_invite_submitters(submitter, key = 'invite_by_uuid') diff --git a/app/controllers/submit_form_values_controller.rb b/app/controllers/submit_form_values_controller.rb index 2c4a2ad3..e1a6b9ab 100644 --- a/app/controllers/submit_form_values_controller.rb +++ b/app/controllers/submit_form_values_controller.rb @@ -8,7 +8,7 @@ class SubmitFormValuesController < ApplicationController submitter = Submitter.find_by!(slug: params[:submit_form_slug]) return render json: {} if submitter.completed_at? || submitter.declined_at? - return render json: {} if submitter.submission.template.archived_at? || + return render json: {} if submitter.submission.template&.archived_at? || submitter.submission.archived_at? || submitter.submission.expired? From 64cd24a24da3414c7ebd4b95c7b8a8988af0c0af Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 11:04:25 +0300 Subject: [PATCH 12/27] validate blank images --- app/controllers/api/attachments_controller.rb | 6 ++++++ app/javascript/submission_form/initials_step.vue | 11 ++++++++++- app/javascript/submission_form/signature_step.vue | 11 ++++++++++- lib/image_utils.rb | 1 - 4 files changed, 26 insertions(+), 3 deletions(-) diff --git a/app/controllers/api/attachments_controller.rb b/app/controllers/api/attachments_controller.rb index eacabbd6..37e827b5 100644 --- a/app/controllers/api/attachments_controller.rb +++ b/app/controllers/api/attachments_controller.rb @@ -10,6 +10,12 @@ module Api def create submitter = Submitter.find_by!(slug: params[:submitter_slug]) + if params[:type].in?(%w[initials signature]) && ImageUtils.blank?(Vips::Image.new_from_file(params[:file].path)) + Rollbar.error("Empty signature: #{submitter.id}") if defined?(Rollbar) + + return render json: { error: "#{params[:type]} is empty" }, status: :unprocessable_entity + end + attachment = Submitters.create_attachment!(submitter, params) if params[:remember_signature] == 'true' && submitter.email.present? diff --git a/app/javascript/submission_form/initials_step.vue b/app/javascript/submission_form/initials_step.vue index 531b9784..fe36db8f 100644 --- a/app/javascript/submission_form/initials_step.vue +++ b/app/javascript/submission_form/initials_step.vue @@ -362,11 +362,20 @@ export default { formData.append('file', file) formData.append('submitter_slug', this.submitterSlug) formData.append('name', 'attachments') + formData.append('type', 'initials') return fetch(this.baseUrl + '/api/attachments', { method: 'POST', body: formData - }).then((resp) => resp.json()).then((attachment) => { + }).then(async (resp) => { + if (resp.status === 422 || resp.status === 500) { + const data = await resp.json() + + return Promise.reject(new Error(data.error)) + } + + const attachment = await resp.json() + this.$emit('attached', attachment) this.$emit('update:model-value', attachment.uuid) diff --git a/app/javascript/submission_form/signature_step.vue b/app/javascript/submission_form/signature_step.vue index 2011b77a..0b09e8cf 100644 --- a/app/javascript/submission_form/signature_step.vue +++ b/app/javascript/submission_form/signature_step.vue @@ -716,11 +716,20 @@ export default { formData.append('submitter_slug', this.submitterSlug) formData.append('name', 'attachments') formData.append('remember_signature', this.rememberSignature) + formData.append('type', 'signature') return fetch(this.baseUrl + '/api/attachments', { method: 'POST', body: formData - }).then((resp) => resp.json()).then((attachment) => { + }).then(async (resp) => { + if (resp.status === 422 || resp.status === 500) { + const data = await resp.json() + + return Promise.reject(new Error(data.error)) + } + + const attachment = await resp.json() + this.$emit('attached', attachment) this.$emit('update:model-value', attachment.uuid) diff --git a/lib/image_utils.rb b/lib/image_utils.rb index 18f99ad5..57f630a5 100644 --- a/lib/image_utils.rb +++ b/lib/image_utils.rb @@ -9,7 +9,6 @@ module ImageUtils return true if min.all?(255) && max.all?(255) return true if min.all?(0) && max.all?(0) - return true if min.length >= 4 && min[-1].zero? && max[-1].zero? false end From 7eba4865bc23c467b47d793e8b388c1f909a321c Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 11:28:38 +0300 Subject: [PATCH 13/27] fix signature remember --- lib/submitters/maybe_assign_default_browser_signature.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/submitters/maybe_assign_default_browser_signature.rb b/lib/submitters/maybe_assign_default_browser_signature.rb index 98b23131..88431f91 100644 --- a/lib/submitters/maybe_assign_default_browser_signature.rb +++ b/lib/submitters/maybe_assign_default_browser_signature.rb @@ -7,6 +7,8 @@ module Submitters module_function def call(submitter, params, cookies = nil, attachments = []) + attachments = attachments.select { |e| e.record_id == submitter.id && e.record_type == 'Submitter' } + if (value = params[:signature_src].presence || params[:signature].presence) find_or_create_signature_from_value(submitter, value, attachments) elsif params[:signed_signature_uuids].present? From bf2f5b24dc0d30f2afea473b9af9a49db9c8ad78 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 17:15:08 +0300 Subject: [PATCH 14/27] update docs --- docs/api/csharp.md | 1203 ++++++++++++ docs/api/go.md | 1272 ++++++++++++ docs/api/java.md | 1200 ++++++++++++ docs/api/javascript.md | 1272 ++++++++++++ docs/api/nodejs.md | 1290 +++++++++++++ docs/api/php.md | 1266 ++++++++++++ docs/api/python.md | 1275 ++++++++++++ docs/api/ruby.md | 1275 ++++++++++++ docs/api/shell.md | 1200 ++++++++++++ docs/api/typescript.md | 1272 ++++++++++++ docs/embedding/form-builder-angular.md | 22 +- docs/embedding/form-builder-javascript.md | 22 +- docs/embedding/form-builder-react.md | 22 +- docs/embedding/form-builder-vue.md | 22 +- docs/embedding/signing-form-angular.md | 51 +- docs/embedding/signing-form-javascript.md | 41 +- docs/embedding/signing-form-react.md | 51 +- docs/embedding/signing-form-vue.md | 45 +- docs/openapi.json | 2133 +++++++++++++++++++-- 19 files changed, 14731 insertions(+), 203 deletions(-) diff --git a/docs/api/csharp.md b/docs/api/csharp.md index b0b68b36..8df5aeb5 100644 --- a/docs/api/csharp.md +++ b/docs/api/csharp.md @@ -1573,6 +1573,11 @@ var response = client.Execute(request); "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1654,6 +1659,11 @@ var response = client.Execute(request); "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2217,6 +2227,11 @@ var response = client.Execute(request); "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2236,3 +2251,1191 @@ var response = client.Execute(request); } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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/submissions/pdf"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```csharp +var client = new RestClient("https://api.docuseal.com/submissions/html"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```csharp +var client = new RestClient("https://api.docuseal.com/templates/pdf"); +var request = new RestRequest("", Method.Post); +request.AddHeader("X-Auth-Token", "API_KEY"); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}", ParameterType.RequestBody); +var response = client.Execute(request); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/go.md b/docs/api/go.md index 09d65608..83db964f 100644 --- a/docs/api/go.md +++ b/docs/api/go.md @@ -1923,6 +1923,11 @@ func main() { "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -2027,6 +2032,11 @@ func main() { "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2636,6 +2646,11 @@ func main() { "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2655,3 +2670,1260 @@ func main() { } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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/submissions/pdf" + + payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.Header.Add("X-Auth-Token", "API_KEY") + req.Header.Add("content-type", "application/json") + + res, _ := http.DefaultClient.Do(req) + + defer res.Body.Close() + body, _ := io.ReadAll(res.Body) + + fmt.Println(res) + fmt.Println(string(body)) + +} +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/submissions/html" + + payload := strings.NewReader("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```go +package main + +import ( + "fmt" + "strings" + "net/http" + "io" +) + +func main() { + + url := "https://api.docuseal.com/templates/pdf" + + payload := strings.NewReader("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + + req, _ := http.NewRequest("POST", url, payload) + + req.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 PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/java.md b/docs/api/java.md index 5a1adb66..ca3df371 100644 --- a/docs/api/java.md +++ b/docs/api/java.md @@ -1557,6 +1557,11 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1637,6 +1642,11 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2198,6 +2208,11 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2217,3 +2232,1188 @@ HttpResponse response = Unirest.post("https://api.docuseal.com/templates } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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/submissions/pdf") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}],\"submitters\":[{\"role\":\"First Party\",\"email\":\"john.doe@example.com\"}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/submissions/html") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test Submission Document\",\"documents\":[{\"name\":\"Test Document\",\"html\":\"

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```java +HttpResponse response = Unirest.post("https://api.docuseal.com/templates/pdf") + .header("X-Auth-Token", "API_KEY") + .header("content-type", "application/json") + .body("{\"name\":\"Test PDF\",\"documents\":[{\"name\":\"string\",\"file\":\"base64\",\"fields\":[{\"name\":\"string\",\"areas\":[{\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"page\":1}]}]}]}") + .asString(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/javascript.md b/docs/api/javascript.md index ab7b5518..0fea7231 100644 --- a/docs/api/javascript.md +++ b/docs/api/javascript.md @@ -1617,6 +1617,11 @@ and typesetting industry

"type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1705,6 +1710,11 @@ const template = await docuseal.createTemplateFromDocx({ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2294,6 +2304,11 @@ const template = await docuseal.mergeTemplates({ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2313,3 +2328,1260 @@ const template = await docuseal.mergeTemplates({ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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 submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```javascript +const docuseal = require("@docuseal/api"); + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromPdf({ + name: "Test PDF", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/nodejs.md b/docs/api/nodejs.md index 5e052f72..3b099a3a 100644 --- a/docs/api/nodejs.md +++ b/docs/api/nodejs.md @@ -1704,6 +1704,11 @@ const template = await resp.json(); "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1798,6 +1803,11 @@ const template = await resp.json(); "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2399,6 +2409,11 @@ const template = await resp.json(); "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2418,3 +2433,1278 @@ const template = await resp.json(); } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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/submissions/pdf", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] + }) +}); + +const submission = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/submissions/html", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```nodejs +const fetch = require("node-fetch"); + +const resp = await fetch("https://api.docuseal.com/templates/pdf", { + method: "POST", + headers: { + "X-Auth-Token": "API_KEY" + }, + body: JSON.stringify({ + name: "Test PDF", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] + }) +}); + +const template = await resp.json(); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/php.md b/docs/api/php.md index e6911f02..ff02eb85 100644 --- a/docs/api/php.md +++ b/docs/api/php.md @@ -1585,6 +1585,11 @@ and typesetting industry

"type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1671,6 +1676,11 @@ $docuseal->createTemplateFromDocx([ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2256,6 +2266,11 @@ $docuseal->mergeTemplates([ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2275,3 +2290,1254 @@ $docuseal->mergeTemplates([ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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->createSubmissionFromPdf([ + 'name' => 'Test Submission Document', + 'documents' => [ + [ + 'name' => 'string', + 'file' => 'base64', + 'fields' => [ + [ + 'name' => 'string', + 'areas' => [ + [ + 'x' => 0, + 'y' => 0, + 'w' => 0, + 'h' => 0, + 'page' => 1 + ] + ] + ] + ] + ] + ], + 'submitters' => [ + [ + 'role' => 'First Party', + 'email' => 'john.doe@example.com' + ] + ] +]); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```php +$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com'); + +$docuseal->createSubmissionFromHtml([ + 'name' => 'Test Submission Document', + 'documents' => [ + [ + 'name' => 'Test Document', + 'html' => '

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "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." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```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 PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/python.md b/docs/api/python.md index f0060e3f..50edcd4e 100644 --- a/docs/api/python.md +++ b/docs/api/python.md @@ -1633,6 +1633,11 @@ and typesetting industry

"type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1722,6 +1727,11 @@ docuseal.create_template_from_docx({ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2313,6 +2323,11 @@ docuseal.merge_templates({ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2332,3 +2347,1263 @@ docuseal.merge_templates({ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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_submission_from_pdf({ + "name": "Test Submission Document", + "documents": [ + { + "name": "string", + "file": "base64", + "fields": [ + { + "name": "string", + "areas": [ + { + "x": 0, + "y": 0, + "w": 0, + "h": 0, + "page": 1 + } + ] + } + ] + } + ], + "submitters": [ + { + "role": "First Party", + "email": "john.doe@example.com" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.create_submission_from_html({ + "name": "Test Submission Document", + "documents": [ + { + "name": "Test Document", + "html": """

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```python +from docuseal import docuseal + +docuseal.key = "API_KEY" +docuseal.url = "https://api.docuseal.com" + +docuseal.create_template_from_pdf({ + "name": "Test PDF", + "documents": [ + { + "name": "string", + "file": "base64", + "fields": [ + { + "name": "string", + "areas": [ + { + "x": 0, + "y": 0, + "w": 0, + "h": 0, + "page": 1 + } + ] + } + ] + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/ruby.md b/docs/api/ruby.md index e0f21818..cf2cd9fe 100644 --- a/docs/api/ruby.md +++ b/docs/api/ruby.md @@ -1633,6 +1633,11 @@ and typesetting industry

"type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1722,6 +1727,11 @@ Docuseal.create_template_from_docx({ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2313,6 +2323,11 @@ Docuseal.merge_templates({ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2332,3 +2347,1263 @@ Docuseal.merge_templates({ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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_submission_from_pdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.create_submission_from_html({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: "

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```ruby +require "docuseal" + +Docuseal.key = ENV["DOCUSEAL_API_KEY"] +Docuseal.url = "https://api.docuseal.com" + +Docuseal.create_template_from_pdf({ + name: "Test PDF", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] +}) +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/shell.md b/docs/api/shell.md index ec286be1..02016519 100644 --- a/docs/api/shell.md +++ b/docs/api/shell.md @@ -1557,6 +1557,11 @@ curl --request POST \ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1637,6 +1642,11 @@ curl --request POST \ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2198,6 +2208,11 @@ curl --request POST \ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2217,3 +2232,1188 @@ curl --request POST \ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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/submissions/pdf \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test Submission Document","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```shell +curl --request POST \ + --url https://api.docuseal.com/submissions/html \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test Submission Document","documents":[{"name":"Test Document","html":"

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```shell +curl --request POST \ + --url https://api.docuseal.com/templates/pdf \ + --header 'X-Auth-Token: API_KEY' \ + --header 'content-type: application/json' \ + --data '{"name":"Test PDF","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}]}' +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/api/typescript.md b/docs/api/typescript.md index 9ee334ce..d2bd2a7e 100644 --- a/docs/api/typescript.md +++ b/docs/api/typescript.md @@ -1617,6 +1617,11 @@ and typesetting industry

"type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -1705,6 +1710,11 @@ const template = await docuseal.createTemplateFromDocx({ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -2294,6 +2304,11 @@ const template = await docuseal.mergeTemplates({ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -2313,3 +2328,1260 @@ const template = await docuseal.mergeTemplates({ } ``` +### Create a submission from PDF + +The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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 submission = await docuseal.createSubmissionFromPdf({ + name: "Test Submission Document", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ], + submitters: [ + { + role: "First Party", + email: "john.doe@example.com" + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "operationId": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + +### Create a submission from HTML + +This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const submission = await docuseal.createSubmissionFromHtml({ + name: "Test Submission Document", + documents: [ + { + name: "Test Document", + html: `

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

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

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + } +} +``` + +### Create a template from PDF + +The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form + + +```typescript +import docuseal from "@docuseal/api"; + +docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" }); + +const template = await docuseal.createTemplateFromPdf({ + name: "Test PDF", + documents: [ + { + name: "string", + file: "base64", + fields: [ + { + name: "string", + areas: [ + { + x: 0, + y: 0, + w: 0, + h: 0, + page: 1 + } + ] + } + ] + } + ] +}); +``` + +```json +{ + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Templates" + ], + "summary": "Create a template from PDF", + "operationId": "createTemplateFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the template", + "example": "Test PDF" + }, + "folder_name": { + "type": "string", + "description": "The folder's name to which the template should be created." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", + "example": "unique-key" + }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + }, + "preferences": { + "type": "object", + "properties": { + "font_size": { + "type": "integer", + "description": "Font size of the field value in pixels.", + "example": 12 + }, + "font_type": { + "type": "string", + "description": "Font type of the field value.", + "enum": [ + "bold", + "italic", + "bold_italic" + ] + }, + "font": { + "type": "string", + "description": "Font family of the field value.", + "enum": [ + "Times", + "Helvetica", + "Courier" + ] + }, + "color": { + "type": "string", + "description": "Font color of the field value.", + "enum": [ + "black", + "white", + "blue" + ], + "default": "black" + }, + "align": { + "type": "string", + "description": "Horizontal alignment of the field text value.", + "enum": [ + "left", + "center", + "right" + ], + "default": "left" + }, + "valign": { + "type": "string", + "description": "Vertical alignment of the field text value.", + "enum": [ + "top", + "center", + "bottom" + ], + "default": "center" + }, + "format": { + "type": "string", + "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", + "example": "DD/MM/YYYY" + }, + "price": { + "type": "number", + "description": "Price value of the payment field. Only for payment fields.", + "example": 99.99 + }, + "currency": { + "type": "string", + "description": "Currency value of the payment field. Only for payment fields.", + "enum": [ + "USD", + "EUR", + "GBP", + "CAD", + "AUD" + ], + "default": "USD" + }, + "mask": { + "description": "Set `true` to make sensitive data masked on the document.", + "oneOf": [ + { + "type": "integer" + }, + { + "type": "boolean" + } + ], + "default": false + } + } + } + } + } + } + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + } +} +``` + diff --git a/docs/embedding/form-builder-angular.md b/docs/embedding/form-builder-angular.md index 61346f60..89eb9c65 100644 --- a/docs/embedding/form-builder-angular.md +++ b/docs/embedding/form-builder-angular.md @@ -132,7 +132,27 @@ const token = jwt.sign({ "fieldTypes": { "type": "array", "required": false, - "description": "Field type names to be used in the form builder. All field types are used by default." + "description": "Field type names to be used in the form builder. All field types are used by default.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "datenow", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] }, "drawFieldType": { "type": "string", diff --git a/docs/embedding/form-builder-javascript.md b/docs/embedding/form-builder-javascript.md index ecd795b1..64cb8eaf 100644 --- a/docs/embedding/form-builder-javascript.md +++ b/docs/embedding/form-builder-javascript.md @@ -317,7 +317,27 @@ "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" + "example": "text,date", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "datenow", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] }, "data-draw-field-type": { "type": "string", diff --git a/docs/embedding/form-builder-react.md b/docs/embedding/form-builder-react.md index 21bf8efc..e38a146a 100644 --- a/docs/embedding/form-builder-react.md +++ b/docs/embedding/form-builder-react.md @@ -123,7 +123,27 @@ const token = jwt.sign({ "fieldTypes": { "type": "array", "required": false, - "description": "Field type names to be used in the form builder. All field types are used by default." + "description": "Field type names to be used in the form builder. All field types are used by default.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "datenow", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] }, "drawFieldType": { "type": "string", diff --git a/docs/embedding/form-builder-vue.md b/docs/embedding/form-builder-vue.md index a7194c4e..698360aa 100644 --- a/docs/embedding/form-builder-vue.md +++ b/docs/embedding/form-builder-vue.md @@ -144,7 +144,27 @@ const token = jwt.sign({ "field-types": { "type": "array", "required": false, - "description": "Field type names to be used in the form builder. All field types are used by default." + "description": "Field type names to be used in the form builder. All field types are used by default.", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "datenow", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] }, "draw-field-type": { "type": "string", diff --git a/docs/embedding/signing-form-angular.md b/docs/embedding/signing-form-angular.md index 63a5a434..8bbad1a0 100644 --- a/docs/embedding/signing-form-angular.md +++ b/docs/embedding/signing-form-angular.md @@ -48,6 +48,41 @@ export class AppComponent {} "description": "The role name or title of the signer.", "example": "First Party" }, + "token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key. JWT can be generated only on the backend..", + "required": false, + "properties": { + "slug": { + "type": "string", + "required": true, + "description": "Template or Submitter slug. When Submitter slug is used no need to pass additional email param." + }, + "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 with Template slug." + }, + "external_id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + } + } + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it. Completed documents embedded in preview mode require `data-token` authentication." + }, "expand": { "type": "boolean", "required": false, @@ -66,11 +101,6 @@ export class AppComponent {} "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, @@ -87,12 +117,6 @@ export class AppComponent {} "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, @@ -242,6 +266,11 @@ export class AppComponent {} "description": "Pre-assigned values for form fields.", "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" }, + "externalId": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, "metadata": { "type": "object", "required": false, diff --git a/docs/embedding/signing-form-javascript.md b/docs/embedding/signing-form-javascript.md index 05d375aa..9674bb35 100644 --- a/docs/embedding/signing-form-javascript.md +++ b/docs/embedding/signing-form-javascript.md @@ -42,6 +42,41 @@ "description": "The role name or title of the signer.", "example": "First Party" }, + "data-token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key. JWT can be generated only on the backend..", + "required": false, + "properties": { + "slug": { + "type": "string", + "required": true, + "description": "Template or Submitter slug. When Submitter slug is used no need to pass additional email param." + }, + "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 with Template slug." + }, + "external_id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + } + } + }, + "data-preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it. Completed documents embedded in preview mode require `data-token` authentication." + }, "data-expand": { "type": "boolean", "required": false, @@ -60,12 +95,6 @@ "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, diff --git a/docs/embedding/signing-form-react.md b/docs/embedding/signing-form-react.md index 8c0c1f9b..91039bbf 100644 --- a/docs/embedding/signing-form-react.md +++ b/docs/embedding/signing-form-react.md @@ -45,6 +45,41 @@ export function App() { "description": "The role name or title of the signer.", "example": "First Party" }, + "token": { + "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key. JWT can be generated only on the backend..", + "required": false, + "properties": { + "slug": { + "type": "string", + "required": true, + "description": "Template or Submitter slug. When Submitter slug is used no need to pass additional email param." + }, + "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 with Template slug." + }, + "external_id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + } + } + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it. Completed documents embedded in preview mode require `token` authentication." + }, "expand": { "type": "boolean", "required": false, @@ -63,11 +98,6 @@ export function App() { "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, @@ -84,12 +114,6 @@ export function App() { "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, @@ -239,6 +263,11 @@ export function App() { "description": "Pre-assigned values for form fields.", "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" }, + "externalId": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, "metadata": { "type": "object", "required": false, diff --git a/docs/embedding/signing-form-vue.md b/docs/embedding/signing-form-vue.md index afe1c597..45e6a336 100644 --- a/docs/embedding/signing-form-vue.md +++ b/docs/embedding/signing-form-vue.md @@ -54,10 +54,40 @@ export default { "description": "The role name or title of the signer.", "example": "First Party" }, - "external-id": { + "token": { "type": "string", + "doc_type": "object", + "description": "JSON Web Token (JWT HS256) with a payload signed using the API key. JWT can be generated only on the backend..", "required": false, - "description": "Your application-specific unique string key to identify signer within your app." + "properties": { + "slug": { + "type": "string", + "required": true, + "description": "Template or Submitter slug. When Submitter slug is used no need to pass additional email param." + }, + "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 with Template slug." + }, + "external_id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it." + } + } + }, + "preview": { + "type": "boolean", + "required": false, + "default": false, + "description": "Show form in preview mode without ability to submit it. Completed documents embedded in preview mode require `data-token` authentication." }, "expand": { "type": "boolean", @@ -93,12 +123,6 @@ export default { "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, @@ -249,6 +273,11 @@ export default { "description": "Pre-assigned values for form fields.", "example": "{ 'First Name': 'Jon', 'Last Name': 'Doe' }" }, + "external-id": { + "type": "string", + "required": false, + "description": "Your application-specific unique string key to identify signer within your app." + }, "metadata": { "type": "object", "required": false, diff --git a/docs/openapi.json b/docs/openapi.json index 93f4dabf..e1960410 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -406,6 +406,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -545,6 +549,7 @@ "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -864,6 +869,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -974,6 +983,7 @@ "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -1274,7 +1284,6 @@ "created_at", "updated_at", "submitters", - "template", "created_by_user" ], "properties": { @@ -1282,6 +1291,11 @@ "type": "integer", "description": "Submission unique ID number." }, + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, "source": { "type": "string", "description": "The source of the submission.", @@ -1557,6 +1571,7 @@ "data": [ { "id": 1, + "name": null, "source": "link", "submitters_order": "random", "slug": "VyL4szTwYoSvXq", @@ -2216,7 +2231,6 @@ "updated_at", "archived_at", "submitters", - "template", "created_by_user", "submission_events", "documents", @@ -2229,6 +2243,11 @@ "type": "integer", "description": "Submission unique ID number." }, + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, "slug": { "type": "string", "description": "Unique slug of the submission." @@ -2611,6 +2630,7 @@ }, "example": { "id": 1, + "name": null, "source": "link", "submitters_order": "random", "slug": "VyL4szTwYoSvXq", @@ -2965,170 +2985,1908 @@ { "type": "string" }, - { - "type": "number" + { + "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" + } + ] + } + } + } + } + } + }, + "/submissions/pdf": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from PDF", + "description": "The API endpoint provides the functionality to create one-off submission request from a PDF or DOCX 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": "createSubmissionFromPdf", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission.", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "file" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document." + }, + "file": { + "example": "base64", + "type": "string", + "format": "base64", + "description": "Base64-encoded content of the PDF or DOCX file or downloadable file URL." + }, + "fields": { + "type": "array", + "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the field." + }, + "type": { + "type": "string", + "description": "Type of the field (e.g., text, signature, date, initials).", + "enum": [ + "heading", + "text", + "signature", + "initials", + "date", + "number", + "image", + "checkbox", + "multiple", + "file", + "radio", + "select", + "cells", + "stamp", + "payment", + "phone", + "verification" + ] + }, + "role": { + "type": "string", + "description": "Role name of the signer." + }, + "required": { + "type": "boolean", + "description": "Indicates if the field is required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "areas": { + "type": "array", + "items": { + "type": "object", + "required": [ + "x", + "y", + "w", + "h", + "page" + ], + "properties": { + "x": { + "type": "number", + "description": "X-coordinate of the field area." + }, + "y": { + "type": "number", + "description": "Y-coordinate of the field area." + }, + "w": { + "type": "number", + "description": "Width of the field area." + }, + "h": { + "type": "number", + "description": "Height of the field area." + }, + "page": { + "type": "integer", + "description": "Page number of the field area. Starts from 1.", + "example": 1 + }, + "option": { + "type": "string", + "description": "Option string value for 'radio' and 'multiple' select field types." + } + } + } + }, + "options": { + "type": "array", + "description": "An array of option values for 'select' field type.", + "items": { + "type": "string" + }, + "example": [ + "Option A", + "Option B" + ] + } + } + } + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "submitters", + "source", + "submitters_order", + "status", + "documents", + "expire_at", + "created_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "name": { + "type": "string", + "description": "Submission name." + }, + "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." + }, + "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." + }, + "embed_src": { + "type": "string", + "description": "The `src` URL value to embed the signing form or sign via a link." + } + } + } + }, + "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" + ] + }, + "status": { + "type": "string", + "description": "The status of the submission.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "schema": { + "type": "array", + "description": "The one-off submission 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": "List of fields to be filled in the one-off submission.", + "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." + } + } + } + } + } + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the one-off submission.", + "items": { + "type": "object", + "required": [ + "attachment_uuid", + "name" + ], + "properties": { + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the one-off submission." + }, + "name": { + "type": "string", + "description": "Name of the attached document to the one-off submission." + } + } + } + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "created_at": { + "type": "string", + "description": "The date and time when the submission was created." + } + } + }, + "example": { + "id": 5, + "name": "Test Submission", + "submitters": [ + { + "id": 1, + "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", + "email": "john.doe@example.com", + "slug": "pAMimKcyrLjqVt", + "sent_at": "2025-06-02T15:55:51.310Z", + "opened_at": null, + "completed_at": null, + "declined_at": null, + "created_at": "2025-06-02T15:55:50.320Z", + "updated_at": "2025-06-02T15:55:50.320Z", + "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, + "reply_to": "reply@example.com", + "completed_redirect_url": "https://example.com/" + }, + "role": "First Party", + "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" + } + ], + "source": "api", + "submitters_order": "preserved", + "status": "pending", + "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 + } + ] + } + ], + "expire_at": null, + "created_at": "2025-06-02T15:55:50.270Z" + } + } + } + } + } + } + }, + "/submissions/html": { + "post": { + "security": [ + { + "AuthToken": [] + } + ], + "tags": [ + "Submissions" + ], + "summary": "Create a submission from HTML", + "description": "This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.
Related Guides
Create PDF document fillable form with HTML", + "operationId": "createSubmissionFromHtml", + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "documents", + "submitters" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the document submission", + "example": "Test Submission Document" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "order": { + "type": "string", + "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", + "default": "preserved", + "enum": [ + "preserved", + "random" + ] + }, + "completed_redirect_url": { + "type": "string", + "description": "Specify URL to redirect to after the submission completion." + }, + "bcc_completed": { + "type": "string", + "description": "Specify BCC address to send signed documents to after the completion." + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails." + }, + "expire_at": { + "type": "string", + "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", + "example": "2024-09-01 12:00:00 UTC" + }, + "template_ids": { + "type": "array", + "description": "An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates.", + "items": { + "type": "integer", + "description": "The ID of the template to use for the submission." + } + }, + "documents": { + "type": "array", + "description": "The list of documents built from HTML. Can be used to create a submission with multiple documents.", + "items": { + "type": "object", + "required": [ + "html" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name. Random uuid will be assigned when not specified.", + "example": "Test Document" + }, + "html": { + "type": "string", + "description": "HTML document content with field tags.", + "example": "

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

\n" + }, + "html_header": { + "type": "string", + "description": "HTML document content of the header to be displayed on every page." + }, + "html_footer": { + "type": "string", + "description": "HTML document content of the footer to be displayed on every page." + }, + "size": { + "type": "string", + "default": "Letter", + "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", + "enum": [ + "Letter", + "Legal", + "Tabloid", + "Ledger", + "A0", + "A1", + "A2", + "A3", + "A4", + "A5", + "A6" + ], + "example": "A4" + }, + "position": { + "type": "integer", + "description": "Document position in the submission. If not specified, the document will be added in the order it appears in the documents array." + } + } + } + }, + "submitters": { + "type": "array", + "description": "The list of submitters for the submission.", + "items": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the submitter." + }, + "role": { + "type": "string", + "description": "The role name or title of the submitter.", + "example": "First Party" + }, + "email": { + "type": "string", + "description": "The email address of the submitter.", + "format": "email", + "example": "john.doe@example.com" + }, + "phone": { + "type": "string", + "description": "The phone number of the submitter, formatted according to the E.164 standard.", + "example": "+1234567890" + }, + "values": { + "type": "object", + "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." + }, + "external_id": { + "type": "string", + "description": "Your application-specific unique string key to identify this submitter within your app." + }, + "completed": { + "type": "boolean", + "description": "Pass `true` to mark submitter as completed and auto-signed via API." + }, + "metadata": { + "type": "object", + "description": "Metadata object with additional submitter information.", + "example": "{ \"customField\": \"value\" }" + }, + "send_email": { + "type": "boolean", + "description": "Set `false` to disable signature request emails sending only for this submitter.", + "default": true + }, + "send_sms": { + "type": "boolean", + "description": "Set `true` to send signature request via phone number and SMS.", + "default": false + }, + "reply_to": { + "type": "string", + "description": "Specify Reply-To address to use in the notification emails for this submitter." + }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "fields": { + "type": "array", + "description": "A list of configurations for document form fields.", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Document field name.", + "example": "First Name" + }, + "default_value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + } + ], + "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", + "example": "Acme" + }, + "readonly": { + "type": "boolean", + "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", + "default": false + }, + "required": { + "type": "boolean", + "description": "Set `true` to make the field required." + }, + "title": { + "type": "string", + "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." + }, + "description": { + "type": "string", + "description": "Field description displayed on the signing form. Supports Markdown." + }, + "validation_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" + } + } + } + } + }, + "message": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Custom signature request email subject." + }, + "body": { + "type": "string", + "description": "Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}." + } + } + }, + "merge_documents": { + "type": "boolean", + "description": "Set `true` to merge the documents into a single PDF file.", + "default": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "submitters", + "source", + "submitters_order", + "status", + "documents", + "expire_at", + "created_at" + ], + "properties": { + "id": { + "type": "integer", + "description": "Submission unique ID number." + }, + "name": { + "type": "string", + "description": "Submission name." + }, + "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." + }, + "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." + }, + "embed_src": { + "type": "string", + "description": "The `src` URL value to embed the signing form or sign via a link." + } + } + } + }, + "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" + ] + }, + "status": { + "type": "string", + "description": "The status of the submission.", + "enum": [ + "completed", + "declined", + "expired", + "pending" + ] + }, + "schema": { + "type": "array", + "description": "The one-off submission 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": "List of fields to be filled in the one-off submission.", + "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." }, - { - "type": "boolean" + "attachment_uuid": { + "type": "string", + "description": "Unique identifier of the attached document where the field is located." }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } + "page": { + "type": "integer", + "description": "Page number of the attached document where the field is located." } - ], - "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": { + } + }, + "documents": { + "type": "array", + "description": "List of documents attached to the one-off submission.", + "items": { "type": "object", + "required": [ + "attachment_uuid", + "name" + ], "properties": { - "send_email": { - "type": "boolean", - "description": "Indicates whether the signature request email should be sent." + "attachment_uuid": { + "type": "string", + "description": "Unique indentifier of attached document to the one-off submission." }, - "send_sms": { - "type": "boolean", - "description": "Indicates whether the signature request should be sent via SMS." + "name": { + "type": "string", + "description": "Name of the attached document to the one-off submission." } } - }, - "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 + "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" }, - "role": "First Party", - "embed_src": "SEwc65vHNDH3QS" + "created_at": { + "type": "string", + "description": "The date and time when the submission was created." + } } - ] + }, + "example": { + "id": 5, + "name": "Test Submission", + "submitters": [ + { + "id": 1, + "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", + "email": "john.doe@example.com", + "slug": "pAMimKcyrLjqVt", + "sent_at": "2025-06-02T15:55:51.310Z", + "opened_at": null, + "completed_at": null, + "declined_at": null, + "created_at": "2025-06-02T15:55:50.320Z", + "updated_at": "2025-06-02T15:55:50.320Z", + "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, + "reply_to": "reply@example.com", + "completed_redirect_url": "https://example.com/" + }, + "role": "First Party", + "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" + } + ], + "source": "api", + "submitters_order": "preserved", + "status": "pending", + "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 + } + ] + } + ], + "expire_at": null, + "created_at": "2025-06-02T15:55:50.270Z" + } } } } @@ -4736,6 +6494,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -5179,6 +6941,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -5287,6 +7053,7 @@ "folder_id": 2, "folder_name": "Default", "external_id": null, + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -5378,6 +7145,11 @@ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", @@ -5670,6 +7442,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -5778,6 +7554,7 @@ "folder_id": 1, "folder_name": "Default", "external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c", + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -5836,6 +7613,11 @@ "type": "string", "description": "The folder's name to which the template should be created." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -6315,6 +8097,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -6423,6 +8209,7 @@ "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -6453,8 +8240,8 @@ "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", + "summary": "Create a template from PDF", + "description": "The API endpoint provides the functionality to create a fillable document template for a PDF file. Use {{Field Name;role=Signer1;type=date}} text tags to define fillable fields in the document. See https://www.docuseal.com/examples/fieldtags.pdf for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
Related Guides
Use embedded text field tags to create a fillable form\n", "operationId": "createTemplateFromPdf", "parameters": [], "requestBody": { @@ -6481,6 +8268,11 @@ "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", "example": "unique-key" }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "documents": { "type": "array", "items": { @@ -6694,19 +8486,19 @@ } } } - }, - "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 } } } + }, + "flatten": { + "type": "boolean", + "description": "Remove PDF form fields from the documents.", + "default": false + }, + "remove_tags": { + "type": "boolean", + "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", + "default": true } } } @@ -6978,6 +8770,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -7086,6 +8882,7 @@ "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", + "shared_link": true, "author": { "id": 1, "first_name": "John", @@ -7154,6 +8951,11 @@ "type": "string", "description": "Your application-specific unique string key to identify this template within your app." }, + "shared_link": { + "type": "boolean", + "description": "set to `true` to make the template available via a shared link. This will allow anyone with the link to create a submission from this template.", + "default": true + }, "roles": { "type": "array", "description": "An array of submitter role names to be used in the merged template.", @@ -7435,6 +9237,10 @@ "type": "string", "description": "Folder name where the template is placed." }, + "shared_link": { + "type": "boolean", + "description": "Indicates if the template is accessible by link." + }, "author": { "type": "object", "required": [ @@ -7543,6 +9349,7 @@ "folder_id": 2, "folder_name": "Default", "external_id": null, + "shared_link": true, "author": { "id": 1, "first_name": "John", From cd477c880cd7f08902618ec92189ac8a71939e93 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Thu, 26 Jun 2025 21:44:05 +0300 Subject: [PATCH 15/27] render image as file --- app/views/submissions/_value.html.erb | 4 ++-- app/views/submissions/show.html.erb | 4 ++-- lib/submissions/generate_audit_trail.rb | 7 ++++--- lib/submissions/generate_result_attachments.rb | 6 +++++- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/app/views/submissions/_value.html.erb b/app/views/submissions/_value.html.erb index 546ce26f..38ae36ea 100644 --- a/app/views/submissions/_value.html.erb +++ b/app/views/submissions/_value.html.erb @@ -28,9 +28,9 @@
<% end %> - <% elsif field['type'].in?(['image', 'initials', 'stamp']) %> + <% elsif field['type'].in?(['image', 'initials', 'stamp']) && attachments_index[value].image? %> - <% elsif field['type'].in?(['file', 'payment']) %> + <% elsif field['type'].in?(['file', 'payment', 'image']) %>
<% Array.wrap(value).each do |val| %> diff --git a/app/views/submissions/show.html.erb b/app/views/submissions/show.html.erb index 33f507ac..edadd1a7 100644 --- a/app/views/submissions/show.html.erb +++ b/app/views/submissions/show.html.erb @@ -244,9 +244,9 @@
- <% elsif field['type'].in?(['image', 'stamp']) %> + <% elsif field['type'].in?(['image', 'stamp']) && attachments_index[value].image? %> - <% elsif field['type'] == 'file' || field['type'] == 'payment' %> + <% elsif field['type'].in?(['file', 'payment', 'image']) %>
<% Array.wrap(value).each do |val| %> diff --git a/lib/submissions/generate_audit_trail.rb b/lib/submissions/generate_audit_trail.rb index d15c242b..51d3e190 100644 --- a/lib/submissions/generate_audit_trail.rb +++ b/lib/submissions/generate_audit_trail.rb @@ -312,8 +312,9 @@ module Submissions text_align: field_name.to_s.match?(RTL_REGEXP) ? :right : :left, line_spacing: 1.3, padding: [0, 0, 2, 0] ), - if field['type'].in?(%w[image signature initials stamp]) - attachment = submitter.attachments.find { |a| a.uuid == value } + if field['type'].in?(%w[image signature initials stamp]) && + (attachment = submitter.attachments.find { |a| a.uuid == value }) && + attachment.image? image = begin @@ -340,7 +341,7 @@ module Submissions composer.image(io, width:, height:, margin: [5, 0, 10, 0]) composer.formatted_text_box([{ text: '' }]) - elsif field['type'].in?(%w[file payment]) + elsif field['type'].in?(%w[file payment image]) if field['type'] == 'payment' unit = CURRENCY_SYMBOLS[field['preferences']['currency']] || field['preferences']['currency'] diff --git a/lib/submissions/generate_result_attachments.rb b/lib/submissions/generate_result_attachments.rb index bdfff77b..6d690358 100644 --- a/lib/submissions/generate_result_attachments.rb +++ b/lib/submissions/generate_result_attachments.rb @@ -252,7 +252,11 @@ module Submissions canvas = page.canvas(type: :overlay) canvas.font(FONT_NAME, size: font_size) - case field['type'] + field_type = field['type'] + field_type = 'file' if field_type == 'image' && + !submitter.attachments.find { |a| a.uuid == value }.image? + + case field_type when ->(type) { type == 'signature' && (with_signature_id || field.dig('preferences', 'reason_field_uuid')) } attachment = submitter.attachments.find { |a| a.uuid == value } From 57503eefd2cbf537018fd390f3438527c262b61b Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Fri, 27 Jun 2025 10:13:29 +0300 Subject: [PATCH 16/27] adjust search index --- lib/search_entries.rb | 30 +++++++++++++++++++++--------- lib/submitters.rb | 2 +- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/lib/search_entries.rb b/lib/search_entries.rb index 5281dbf3..cbd9061c 100644 --- a/lib/search_entries.rb +++ b/lib/search_entries.rb @@ -56,7 +56,7 @@ module SearchEntries end [sql, number, number.length > 1 ? number.delete_prefix('0') : number, keyword] - elsif keyword.match?(/[^\p{L}\d&@._\-]/) || keyword.match?(/\A['"].*['"]\z/) + elsif keyword.match?(/[^\p{L}\d&@.\-]/) || keyword.match?(/\A['"].*['"]\z/) ['tsvector @@ plainto_tsquery(?)', TextUtils.transliterate(keyword.downcase)] else keyword = TextUtils.transliterate(keyword.downcase).squish @@ -180,15 +180,21 @@ module SearchEntries end def index_template(template) - sql = SearchEntry.sanitize_sql_array( - ["SELECT to_tsvector(:text), to_tsvector('simple', :text)", - { text: TextUtils.transliterate(template.name.to_s.downcase).delete("\0") }] - ) + text = TextUtils.transliterate(template.name.to_s.downcase.squish).delete("\0") + + sql = SearchEntry.sanitize_sql_array(["SELECT to_tsvector(:text), to_tsvector('simple', :text)", { text: }]) entry = template.search_entry || template.build_search_entry entry.account_id = template.account_id entry.tsvector, ngram = SearchEntry.connection.select_rows(sql).first + + hyphens = text.scan(/\b[^\s]*?\d-[^\s]+?\b/) + text.scan(/\b[^\s]+-\d[^\s]*?\b/) + + hyphens.uniq.each_with_index do |item, index| + entry.tsvector += " '#{item.delete("'")}':#{index + 1}" unless entry.tsvector.include?(item) + end + entry.ngram = build_ngram(ngram) return if entry.tsvector.blank? @@ -205,15 +211,21 @@ module SearchEntries def index_submission(submission) return if submission.name.blank? - sql = SearchEntry.sanitize_sql_array( - ["SELECT to_tsvector(:text), to_tsvector('simple', :text)", - { text: TextUtils.transliterate(submission.name.to_s.downcase).delete("\0") }] - ) + text = TextUtils.transliterate(submission.name.to_s.downcase.squish).delete("\0") + + sql = SearchEntry.sanitize_sql_array(["SELECT to_tsvector(:text), to_tsvector('simple', :text)", { text: }]) entry = submission.search_entry || submission.build_search_entry entry.account_id = submission.account_id entry.tsvector, ngram = SearchEntry.connection.select_rows(sql).first + + hyphens = text.scan(/\b[^\s]*?\d-[^\s]+?\b/) + text.scan(/\b[^\s]+-\d[^\s]*?\b/) + + hyphens.uniq.each_with_index do |item, index| + entry.tsvector += " '#{item.delete("'")}':#{index + 1}" unless entry.tsvector.include?(item) + end + entry.ngram = build_ngram(ngram) return if entry.tsvector.blank? diff --git a/lib/submitters.rb b/lib/submitters.rb index 65bc4215..b5d84d48 100644 --- a/lib/submitters.rb +++ b/lib/submitters.rb @@ -53,7 +53,7 @@ module Submitters end [sql, number, weight, number.length > 1 ? number.delete_prefix('0') : number, weight] - elsif keyword.match?(/[^\p{L}\d&@._\-]/) + elsif keyword.match?(/[^\p{L}\d&@.\-]/) terms = TextUtils.transliterate(keyword.downcase).split(/\b/).map(&:squish).compact_blank.uniq if terms.size > 1 From 0e33e23d1f6abf234daf293c629c69590643789f Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Fri, 27 Jun 2025 12:49:25 +0300 Subject: [PATCH 17/27] fix prefill condition --- lib/submitters/submit_values.rb | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/lib/submitters/submit_values.rb b/lib/submitters/submit_values.rb index 8775f26e..eb9e26a4 100644 --- a/lib/submitters/submit_values.rb +++ b/lib/submitters/submit_values.rb @@ -219,8 +219,7 @@ module Submitters submitters_values = nil has_other_submitters = submission.template_submitters.size > 1 - has_document_conditions = - (submission.template_schema || submission.template.schema).any? { |e| e['conditions'].present? } + has_document_conditions = submission_has_document_conditions?(submission) attachments_index = if has_document_conditions @@ -234,7 +233,7 @@ module Submitters if has_document_conditions && !check_field_areas_attachments(field, attachments_index) submitter.values.delete(field['uuid']) - required_field_uuids_acc.delete(field['uuid']) + required_field_uuids_acc&.delete(field['uuid']) end if has_other_submitters && !submitters_values && @@ -244,13 +243,17 @@ module Submitters unless check_field_conditions(submitters_values || submitter.values, field, submission.fields_uuid_index) submitter.values.delete(field['uuid']) - required_field_uuids_acc.delete(field['uuid']) + required_field_uuids_acc&.delete(field['uuid']) end end submitter.values end + def submission_has_document_conditions?(submission) + (submission.template_schema || submission.template.schema).any? { |e| e['conditions'].present? } + end + def required_editable_field?(field) return false if NONEDITABLE_FIELD_TYPES.include?(field['type']) From 254995c6c6316ea470ebb01307ca5f05f555d1f3 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Fri, 27 Jun 2025 14:45:29 +0300 Subject: [PATCH 18/27] fix missing font variant --- lib/submissions/generate_result_attachments.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/submissions/generate_result_attachments.rb b/lib/submissions/generate_result_attachments.rb index 6d690358..cc7da99a 100644 --- a/lib/submissions/generate_result_attachments.rb +++ b/lib/submissions/generate_result_attachments.rb @@ -223,7 +223,7 @@ module Submissions font_name = FONT_NAME unless font_name.in?(DEFAULT_FONTS) if font_variant != :none && font_name == FONT_NAME - font_name = FONT_VARIANS[font_variant] + font_name = FONT_VARIANS[font_variant] if FONT_VARIANS[font_variant] font_variant = nil unless font_name.in?(DEFAULT_FONTS) end From a6715d40349a3515354ac6b1d8381a9d8089dbb1 Mon Sep 17 00:00:00 2001 From: Alex Turchyn Date: Thu, 26 Jun 2025 16:33:11 +0300 Subject: [PATCH 19/27] add meta description translations --- app/views/start_form/private.html.erb | 4 +++- app/views/start_form/show.html.erb | 4 +++- app/views/submit_form/show.html.erb | 4 +++- config/locales/i18n.yml | 12 ++++++++++++ 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/app/views/start_form/private.html.erb b/app/views/start_form/private.html.erb index 4e16eba4..f976c7f1 100644 --- a/app/views/start_form/private.html.erb +++ b/app/views/start_form/private.html.erb @@ -1,5 +1,7 @@ <% content_for(:html_title, "#{@template.name} | DocuSeal") %> -<% content_for(:html_description, t('share_link_is_currently_disabled')) %> +<% I18n.with_locale(@template.account.locale) do %> + <% content_for(:html_description, t('share_link_is_currently_disabled')) %> +<% end %>
diff --git a/app/views/start_form/show.html.erb b/app/views/start_form/show.html.erb index 7eb0b96f..e8d6db5c 100644 --- a/app/views/start_form/show.html.erb +++ b/app/views/start_form/show.html.erb @@ -1,5 +1,7 @@ <% content_for(:html_title, "#{@template.name} | DocuSeal") %> -<% content_for(:html_description, "#{@template.account.name} has invited you to fill and sign documents online effortlessly with a secure, fast, and user-friendly digital document signing solution.") %> +<% I18n.with_locale(@template.account.locale) do %> + <% content_for(:html_description, t('account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution', account_name: @template.account.name)) %> +<% end %>
diff --git a/app/views/submit_form/show.html.erb b/app/views/submit_form/show.html.erb index bdd5351f..5eb06d9a 100644 --- a/app/views/submit_form/show.html.erb +++ b/app/views/submit_form/show.html.erb @@ -1,5 +1,7 @@ <% content_for(:html_title, "#{@submitter.submission.name || @submitter.submission.template.name} | DocuSeal") %> -<% content_for(:html_description, "#{@submitter.account.name} has invited you to fill and sign documents online effortlessly with a secure, fast, and user-friendly digital document signing solution.") %> +<% I18n.with_locale(@submitter.account.locale) do %> + <% content_for(:html_description, t('account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution', account_name: @submitter.account.name)) %> +<% end %> <% fields_index = Templates.build_field_areas_index(@submitter.submission.template_fields || @submitter.submission.template.fields) %> <% values = @submitter.submission.submitters.reduce({}) { |acc, sub| acc.merge(sub.values) } %> <% submitters_index = @submitter.submission.submitters.index_by(&:uuid) %> diff --git a/config/locales/i18n.yml b/config/locales/i18n.yml index 38fa4213..1ba7b1aa 100644 --- a/config/locales/i18n.yml +++ b/config/locales/i18n.yml @@ -752,6 +752,8 @@ en: &en enable_shared_link: Enable shared link share_link_is_currently_disabled: Share link is currently disabled select_data_residency: Select data residency + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} has invited you to fill and sign documents online effortlessly with a secure, fast, and user-friendly digital document signing solution.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Review or download completed documents. Fill and sign documents online effortlessly with a secure, fast, and user-friendly digital document signing solution. submission_sources: api: API bulk: Bulk Send @@ -1587,6 +1589,8 @@ es: &es enable_shared_link: Habilitar enlace compartido share_link_is_currently_disabled: El enlace compartido está deshabilitado actualmente select_data_residency: Seleccionar ubicación de datos + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} te ha invitado a completar y firmar documentos en línea fácilmente con una solución de firma digital segura, rápida y fácil de usar.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Revisa o descarga los documentos completados. Completa y firma documentos en línea fácilmente con una solución de firma digital segura, rápida y fácil de usar. submission_sources: api: API bulk: Envío masivo @@ -2420,6 +2424,8 @@ it: &it enable_shared_link: Abilita link condiviso share_link_is_currently_disabled: Il link condiviso è attualmente disabilitato select_data_residency: Seleziona la residenza dei dati + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} ti ha invitato a compilare e firmare documenti online con facilità utilizzando una soluzione di firma digitale sicura, veloce e facile da usare.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Rivedi o scarica i documenti completati. Compila e firma documenti online facilmente con una soluzione di firma digitale sicura, veloce e facile da usare. submission_sources: api: API bulk: Invio massivo @@ -3256,6 +3262,8 @@ fr: &fr enable_shared_link: Activer le lien de partage share_link_is_currently_disabled: Le lien de partage est actuellement désactivé select_data_residency: Sélectionner la résidence des données + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} vous a invité à remplir et signer des documents en ligne facilement avec une solution de signature numérique sécurisée, rapide et conviviale.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Consultez ou téléchargez les documents complétés. Remplissez et signez des documents en ligne facilement avec une solution de signature numérique sécurisée, rapide et conviviale. submission_sources: api: API bulk: Envoi en masse @@ -4091,6 +4099,8 @@ pt: &pt enable_shared_link: Ativar link compartilhado share_link_is_currently_disabled: O link compartilhado está desativado no momento select_data_residency: Selecionar local dos dados + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} convidou você para preencher e assinar documentos online com facilidade usando uma solução de assinatura digital segura, rápida e fácil de usar.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Reveja ou baixe os documentos concluídos. Preencha e assine documentos online com facilidade usando uma solução de assinatura digital segura, rápida e fácil de usar. submission_sources: api: API bulk: Envio em massa @@ -4927,6 +4937,8 @@ de: &de enable_shared_link: 'Freigabelink aktivieren' share_link_is_currently_disabled: 'Freigabelink ist derzeit deaktiviert' select_data_residency: Datenstandort auswählen + account_name_has_invited_you_to_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: '%{account_name} hat Sie eingeladen, Dokumente mühelos online mit einer sicheren, schnellen und benutzerfreundlichen digitalen Signaturlösung auszufüllen und zu unterschreiben.' + review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Überprüfen oder laden Sie abgeschlossene Dokumente herunter. Füllen und unterschreiben Sie Dokumente mühelos online mit einer sicheren, schnellen und benutzerfreundlichen digitalen Signaturlösung. submission_sources: api: API bulk: Massenversand From 7b1b4bcf2ca69baf8228d9e860f8c707d5c92f01 Mon Sep 17 00:00:00 2001 From: Alex Turchyn Date: Mon, 23 Jun 2025 19:35:39 +0300 Subject: [PATCH 20/27] show shared link enable button on disabled link page --- .../templates_share_link_controller.rb | 6 ++- app/javascript/elements/check_on_click.js | 2 +- app/views/start_form/private.html.erb | 41 ++++++++++--------- spec/system/signing_form_spec.rb | 27 ++++++++++++ 4 files changed, 54 insertions(+), 22 deletions(-) diff --git a/app/controllers/templates_share_link_controller.rb b/app/controllers/templates_share_link_controller.rb index 5b84f6ca..5dfed111 100644 --- a/app/controllers/templates_share_link_controller.rb +++ b/app/controllers/templates_share_link_controller.rb @@ -10,7 +10,11 @@ class TemplatesShareLinkController < ApplicationController @template.update!(template_params) - head :ok + if params[:redir].present? + redirect_to params[:redir] + else + head :ok + end end private diff --git a/app/javascript/elements/check_on_click.js b/app/javascript/elements/check_on_click.js index 8b3b9ab8..e940dff3 100644 --- a/app/javascript/elements/check_on_click.js +++ b/app/javascript/elements/check_on_click.js @@ -1,7 +1,7 @@ export default class extends HTMLElement { connectedCallback () { this.addEventListener('click', () => { - if (!this.element.checked) { + if (this.element && !this.element.disabled && !this.element.checked) { this.element.checked = true this.element.dispatchEvent(new Event('change', { bubbles: true })) } diff --git a/app/views/start_form/private.html.erb b/app/views/start_form/private.html.erb index f976c7f1..6b8104d6 100644 --- a/app/views/start_form/private.html.erb +++ b/app/views/start_form/private.html.erb @@ -2,29 +2,30 @@ <% I18n.with_locale(@template.account.locale) do %> <% content_for(:html_description, t('share_link_is_currently_disabled')) %> <% end %> -
-
-
-
- <%= render 'banner' %> -

- <%= t('share_link_is_currently_disabled') %> -

+
+
+ <%= render 'banner' %> +

+ <%= t('share_link_is_currently_disabled') %> +

+
+
+
+
+ <%= svg_icon('writing_sign', class: 'w-10 h-10') %>
-
-
-
- <%= svg_icon('writing_sign', class: 'w-10 h-10') %> -
-
-

<%= @template.name %>

- <% if @template.archived_at? %> -

<%= t('form_has_been_deleted_by_html', name: @template.account.name) %>

- <% end %> -
-
+
+

<%= @template.name %>

+ <% if @template.archived_at? %> +

<%= t('form_has_been_deleted_by_html', name: @template.account.name) %>

+ <% end %>
+ <% if can?(:update, @template) %> + + <%= button_to button_title(title: t('enable_shared_link'), icon: svg_icon('lock_open', class: 'w-6 h-6')), template_share_link_path(@template), params: { template: { shared_link: true }, redir: start_form_path(slug: @template.slug) }, method: :post, class: 'white-button w-full' %> + + <% end %>
<%= render 'shared/attribution', link_path: '/start', account: @template.account %> diff --git a/spec/system/signing_form_spec.rb b/spec/system/signing_form_spec.rb index 83c1b30b..3dc2ff98 100644 --- a/spec/system/signing_form_spec.rb +++ b/spec/system/signing_form_spec.rb @@ -848,6 +848,33 @@ RSpec.describe 'Signing Form' do end end + context 'when the template shared link is disabled' do + let(:template) do + create(:template, shared_link: false, account:, author:, only_field_types: %w[text]) + end + + context 'when user is logged in' do + before do + login_as author + visit start_form_path(slug: template.slug) + end + + it 'shows a warning that the shared link is disabled and provides an option to enable it' do + expect(page).to have_content('Share link is currently disabled') + expect(page).to have_content(template.name) + expect(page).to have_button('Enable shared link') + end + + it 'enables the shared link' do + expect do + click_button 'Enable shared link' + end.to change { template.reload.shared_link }.from(false).to(true) + + expect(page).to have_content('You have been invited to submit a form') + end + end + end + it 'sends completed email' do template = create(:template, account:, author:, only_field_types: %w[text signature]) submission = create(:submission, template:) From 13ad614e6b482ada4c8dfda05f540332f099212d Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Sat, 28 Jun 2025 10:17:50 +0300 Subject: [PATCH 21/27] fix rubocop --- .rubocop.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.rubocop.yml b/.rubocop.yml index a679c86a..e3315548 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -66,7 +66,7 @@ RSpec/ExampleLength: Max: 50 RSpec/MultipleMemoizedHelpers: - Max: 9 + Max: 15 Metrics/BlockNesting: Max: 5 From 7fe9ab7601259849961ff8808896ac1ad195d591 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Sat, 28 Jun 2025 10:37:10 +0300 Subject: [PATCH 22/27] update params --- app/controllers/api/submissions_controller.rb | 3 ++- app/controllers/api/submitters_controller.rb | 6 +++++- lib/submitters.rb | 1 + 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/app/controllers/api/submissions_controller.rb b/app/controllers/api/submissions_controller.rb index af784ba2..ef735dfd 100644 --- a/app/controllers/api/submissions_controller.rb +++ b/app/controllers/api/submissions_controller.rb @@ -187,11 +187,12 @@ module Api def submissions_params permitted_attrs = [ :send_email, :send_sms, :bcc_completed, :completed_redirect_url, :reply_to, :go_to_last, - :expire_at, :name, + :require_phone_2fa, :expire_at, :name, { message: %i[subject body], submitters: [[:send_email, :send_sms, :completed_redirect_url, :uuid, :name, :email, :role, :completed, :phone, :application_key, :external_id, :reply_to, :go_to_last, + :require_phone_2fa, { metadata: {}, values: {}, roles: [], readonly_fields: [], message: %i[subject body], fields: [:name, :uuid, :default_value, :value, :title, :description, :readonly, :required, :validation_pattern, :invalid_message, diff --git a/app/controllers/api/submitters_controller.rb b/app/controllers/api/submitters_controller.rb index 3b9a4680..70fb107f 100644 --- a/app/controllers/api/submitters_controller.rb +++ b/app/controllers/api/submitters_controller.rb @@ -82,7 +82,7 @@ module Api submitter_params.permit( :send_email, :send_sms, :reply_to, :completed_redirect_url, :uuid, :name, :email, :role, - :completed, :phone, :application_key, :external_id, :go_to_last, + :completed, :phone, :application_key, :external_id, :go_to_last, :require_phone_2fa, { metadata: {}, values: {}, readonly_fields: [], message: %i[subject body], fields: [[:name, :uuid, :default_value, :value, :required, :readonly, :validation_pattern, :invalid_message, @@ -193,6 +193,10 @@ module Api submitter.preferences['send_sms'] = submitter_preferences['send_sms'] if submitter_preferences.key?('send_sms') submitter.preferences['reply_to'] = submitter_preferences['reply_to'] if submitter_preferences.key?('reply_to') + if submitter_preferences.key?('require_phone_2fa') + submitter.preferences['require_phone_2fa'] = submitter_preferences['require_phone_2fa'] + end + if submitter_preferences.key?('go_to_last') submitter.preferences['go_to_last'] = submitter_preferences['go_to_last'] end diff --git a/lib/submitters.rb b/lib/submitters.rb index b5d84d48..d732120c 100644 --- a/lib/submitters.rb +++ b/lib/submitters.rb @@ -135,6 +135,7 @@ module Submitters preferences['email_message_uuid'] = email_message.uuid if email_message preferences['send_email'] = params['send_email'].in?(TRUE_VALUES) if params.key?('send_email') preferences['send_sms'] = params['send_sms'].in?(TRUE_VALUES) if params.key?('send_sms') + preferences['require_phone_2fa'] = params['require_phone_2fa'].in?(TRUE_VALUES) if params.key?('require_phone_2fa') preferences['bcc_completed'] = params['bcc_completed'] if params.key?('bcc_completed') preferences['reply_to'] = params['reply_to'] if params.key?('reply_to') preferences['go_to_last'] = params['go_to_last'] if params.key?('go_to_last') From b4f80422eb23c058c0ee89ec0e8d8ebfa54bcd49 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Sat, 28 Jun 2025 13:30:05 +0300 Subject: [PATCH 23/27] update doc --- docs/openapi.json | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index e1960410..bb9fa35d 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1773,6 +1773,11 @@ "type": "string", "description": "Submitter specific URL to redirect to after the submission completion." }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { @@ -3422,6 +3427,11 @@ "type": "string", "description": "Submitter specific URL to redirect to after the submission completion." }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, "fields": { "type": "array", "description": "A list of configurations for document form fields.", @@ -4258,6 +4268,11 @@ "type": "string", "description": "Submitter specific URL to redirect to after the submission completion." }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, "fields": { "type": "array", "description": "A list of configurations for document form fields.", @@ -5303,10 +5318,6 @@ "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." @@ -5316,6 +5327,15 @@ "description": "Metadata object with additional submitter information.", "example": "{ \"customField\": \"value\" }" }, + "completed_redirect_url": { + "type": "string", + "description": "Submitter specific URL to redirect to after the submission completion." + }, + "require_phone_2fa": { + "type": "boolean", + "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", + "default": false + }, "message": { "type": "object", "properties": { From 18ee2d531660ffcdbd4bc2f5b96a09b6e0490bd4 Mon Sep 17 00:00:00 2001 From: Alex Turchyn Date: Fri, 13 Jun 2025 16:14:19 +0300 Subject: [PATCH 24/27] add shared link form fields preferences --- app/controllers/start_form_controller.rb | 38 ++++- .../templates_preferences_controller.rb | 2 +- app/javascript/application.js | 2 + .../elements/required_checkbox_group.js | 17 ++ app/views/start_form/completed.html.erb | 2 +- app/views/start_form/show.html.erb | 33 +++- .../_recipients.html.erb | 83 +++++++++ app/views/templates_preferences/show.html.erb | 87 +--------- app/views/templates_share_link/show.html.erb | 33 +++- config/locales/i18n.yml | 116 +++++++++++-- spec/system/signing_form_spec.rb | 157 +++++++++++++++++- 11 files changed, 456 insertions(+), 114 deletions(-) create mode 100644 app/javascript/elements/required_checkbox_group.js create mode 100644 app/views/templates_preferences/_recipients.html.erb diff --git a/app/controllers/start_form_controller.rb b/app/controllers/start_form_controller.rb index fb2a9786..03944f26 100644 --- a/app/controllers/start_form_controller.rb +++ b/app/controllers/start_form_controller.rb @@ -33,7 +33,7 @@ class StartFormController < ApplicationController @submitter = find_or_initialize_submitter(@template, submitter_params) if @submitter.completed_at? - redirect_to start_form_completed_path(@template.slug, email: submitter_params[:email]) + redirect_to start_form_completed_path(@template.slug, submitter_params.compact_blank) else if filter_undefined_submitters(@template).size > 1 && @submitter.new_record? @error_message = multiple_submitters_error_message @@ -49,7 +49,7 @@ class StartFormController < ApplicationController @submitter.assign_attributes(ip: request.remote_ip, ua: request.user_agent) end - if @submitter.save + if @submitter.errors.blank? && @submitter.save if is_new_record enqueue_submission_create_webhooks(@submitter) @@ -71,9 +71,20 @@ class StartFormController < ApplicationController def completed return redirect_to start_form_path(@template.slug) if !@template.shared_link? || @template.archived_at? + submitter_params = params.permit(:name, :email, :phone).tap do |attrs| + attrs[:email] = Submissions.normalize_email(attrs[:email]) + end + + required_fields = @template.preferences.fetch('link_form_fields', ['email']) + + required_params = required_fields.index_with { |key| submitter_params[key] } + + raise ActionController::RoutingError, I18n.t('not_found') if required_params.any? { |_, v| v.blank? } || + required_params.except('name').compact_blank.blank? + @submitter = Submitter.where(submission: @template.submissions) .where.not(completed_at: nil) - .find_by!(email: params[:email]) + .find_by!(required_params) end private @@ -104,7 +115,16 @@ class StartFormController < ApplicationController end def find_or_initialize_submitter(template, submitter_params) - Submitter + required_fields = template.preferences.fetch('link_form_fields', ['email']) + + required_params = required_fields.index_with { |key| submitter_params[key] } + + find_params = required_params.except('name') + + submitter = Submitter.new if find_params.compact_blank.blank? + + submitter ||= + Submitter .where(submission: template.submissions.where(expire_at: Time.current..) .or(template.submissions.where(expire_at: nil)).where(archived_at: nil)) .order(id: :desc) @@ -112,7 +132,15 @@ class StartFormController < ApplicationController .where(external_id: nil) .where(ip: [nil, request.remote_ip]) .then { |rel| params[:resubmit].present? || params[:selfsign].present? ? rel.where(completed_at: nil) : rel } - .find_or_initialize_by(email: submitter_params[:email], **submitter_params.compact_blank) + .find_or_initialize_by(find_params) + + submitter.name = required_params['name'] if submitter.new_record? + + required_params.each do |key, value| + submitter.errors.add(key.to_sym, :blank) if value.blank? + end + + submitter end def assign_submission_attributes(submitter, template) diff --git a/app/controllers/templates_preferences_controller.rb b/app/controllers/templates_preferences_controller.rb index e2ec9ee3..eae2fa9f 100644 --- a/app/controllers/templates_preferences_controller.rb +++ b/app/controllers/templates_preferences_controller.rb @@ -31,7 +31,7 @@ class TemplatesPreferencesController < ApplicationController completed_notification_email_subject completed_notification_email_body completed_notification_email_enabled completed_notification_email_attach_audit] + [completed_message: %i[title body], - submitters: [%i[uuid request_email_subject request_email_body]]] + submitters: [%i[uuid request_email_subject request_email_body]], link_form_fields: []] ).tap do |attrs| attrs[:preferences].delete(:submitters) if params[:request_email_per_submitter] != '1' diff --git a/app/javascript/application.js b/app/javascript/application.js index f951b8fe..6ff4b401 100644 --- a/app/javascript/application.js +++ b/app/javascript/application.js @@ -35,6 +35,7 @@ import SetDateButton from './elements/set_date_button' import IndeterminateCheckbox from './elements/indeterminate_checkbox' import AppTour from './elements/app_tour' import DashboardDropzone from './elements/dashboard_dropzone' +import RequiredCheckboxGroup from './elements/required_checkbox_group' import * as TurboInstantClick from './lib/turbo_instant_click' @@ -105,6 +106,7 @@ safeRegisterElement('indeterminate-checkbox', IndeterminateCheckbox) safeRegisterElement('app-tour', AppTour) safeRegisterElement('dashboard-dropzone', DashboardDropzone) safeRegisterElement('check-on-click', CheckOnClick) +safeRegisterElement('required-checkbox-group', RequiredCheckboxGroup) safeRegisterElement('template-builder', class extends HTMLElement { connectedCallback () { diff --git a/app/javascript/elements/required_checkbox_group.js b/app/javascript/elements/required_checkbox_group.js new file mode 100644 index 00000000..e4dc13d7 --- /dev/null +++ b/app/javascript/elements/required_checkbox_group.js @@ -0,0 +1,17 @@ +export default class extends HTMLElement { + connectedCallback () { + this.querySelectorAll('input[type="checkbox"]').forEach(checkbox => { + checkbox.addEventListener('change', this.handleChange) + }) + } + + handleChange = () => { + if (this.checkedCount !== 0) { + this.closest('form')?.requestSubmit() + } + } + + get checkedCount () { + return this.querySelectorAll('input[type="checkbox"]:checked').length + } +} diff --git a/app/views/start_form/completed.html.erb b/app/views/start_form/completed.html.erb index 003005d8..c21b3d45 100644 --- a/app/views/start_form/completed.html.erb +++ b/app/views/start_form/completed.html.erb @@ -28,7 +28,7 @@ <% end %> <% if Templates.filter_undefined_submitters(@template.submitters).size == 1 && %w[api embed].exclude?(@submitter.submission.source) && @submitter.account.account_configs.find_or_initialize_by(key: AccountConfig::ALLOW_TO_RESUBMIT).value != false && @template.shared_link? %> - <%= button_to button_title(title: t('resubmit'), disabled_with: t('resubmit'), icon: svg_icon('reload', class: 'w-6 h-6')), start_form_path(@template.slug), params: { submitter: { email: params[:email] }, resubmit: true }, method: :put, class: 'white-button w-full' %> + <%= button_to button_title(title: t('resubmit'), disabled_with: t('resubmit'), icon: svg_icon('reload', class: 'w-6 h-6')), start_form_path(@template.slug), params: { submitter: params.permit(:name, :email, :phone).compact_blank, resubmit: true }, method: :put, class: 'white-button w-full' %> <% end %>
diff --git a/app/views/start_form/show.html.erb b/app/views/start_form/show.html.erb index e8d6db5c..75c42e28 100644 --- a/app/views/start_form/show.html.erb +++ b/app/views/start_form/show.html.erb @@ -29,13 +29,32 @@
<% if !@template.archived_at? && !@template.account.archived_at? %> <%= form_for @submitter, url: start_form_path(@template.slug), data: { turbo_frame: :_top }, method: :put, html: { class: 'space-y-4' } do |f| %> -
- <%= f.label :email, t('email'), class: 'label' %> - <%= f.email_field :email, value: current_user&.email || params[:email] || @submitter.email, required: true, class: 'base-input', placeholder: t('provide_your_email_to_start') %> - <% if @error_message %> - <%= @error_message %> - <% end %> -
+ <% if @error_message %> +
+ <%= svg_icon('info_circle', class: 'stroke-current shrink-0 h-6 w-6 mt-1') %> +
<%= @error_message %>
+
+ <% end %> + <% link_form_fields = @template.preferences.fetch('link_form_fields', ['email']) %> + <% multiple_fields = link_form_fields.size > 1 %> + <% if link_form_fields.include?('name') %> +
+ <%= f.label :name, t('name'), class: 'label' %> + <%= f.text_field :name, value: current_user&.full_name || params[:name] || @submitter.name, required: true, class: 'base-input', placeholder: t(multiple_fields ? 'provide_your_name' : 'provide_your_name_to_start') %> +
+ <% end %> + <% if link_form_fields.include?('email') %> +
+ <%= f.label :email, t('email'), class: 'label' %> + <%= f.email_field :email, value: current_user&.email || params[:email] || @submitter.email, required: true, class: 'base-input', placeholder: t(multiple_fields ? 'provide_your_email' : 'provide_your_email_to_start') %> +
+ <% end %> + <% if link_form_fields.include?('phone') %> +
+ <%= f.label :phone, t('phone'), class: 'label' %> + <%= f.telephone_field :phone, value: params[:phone] || @submitter.phone, pattern: '^\+[0-9\s\-]+$', oninvalid: "this.value ? this.setCustomValidity('#{t('use_international_format_1xxx_')}') : ''", oninput: "this.setCustomValidity('')", required: true, class: 'base-input', placeholder: t(multiple_fields ? 'provide_your_phone_in_international_format' : 'provide_your_phone_in_international_format_to_start') %> +
+ <% end %> <%= f.button button_title(title: t('start'), disabled_with: t('starting')), class: 'base-button' %> diff --git a/app/views/templates_preferences/_recipients.html.erb b/app/views/templates_preferences/_recipients.html.erb new file mode 100644 index 00000000..89cf9861 --- /dev/null +++ b/app/views/templates_preferences/_recipients.html.erb @@ -0,0 +1,83 @@ +<% close_on_submit = local_assigns.fetch(:close_on_submit, true) %> +<%= form_for template, url: template_recipients_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-1', id: :submitters_form }, data: { close_on_submit: } do |f| %> + <% unless close_on_submit %> + + <% end %> +
+ <% template.submitters.each_with_index do |submitter, index| %> +
+ <%= f.fields_for :submitters, item = Struct.new(:name, :uuid, :is_requester, :email, :invite_by_uuid, :optional_invite_by_uuid, :linked_to_uuid, :option).new(*submitter.values_at('name', 'uuid', 'is_requester', 'email', 'invite_by_uuid', 'optional_invite_by_uuid', 'linked_to_uuid')), index: do |ff| %> + <% item.option = item.is_requester.present? ? 'is_requester' : (item.email.present? ? 'email' : (item.linked_to_uuid.present? ? "linked_to_#{item.linked_to_uuid}" : (item.invite_by_uuid.present? ? "invite_by_#{item.invite_by_uuid}" : (item.optional_invite_by_uuid.present? ? "optional_invite_by_#{item.optional_invite_by_uuid}" : '')))) %> + <%= ff.hidden_field :uuid %> +
+ <%= ff.text_field :name, class: 'w-full outline-none border-transparent focus:border-transparent focus:ring-0 bg-base-100 px-1 peer mb-2', autocomplete: 'off', placeholder: "#{index + 1}#{(index + 1).ordinal} Party", required: true %> + <% if template.submitters.size == 2 %> + <%= tag.input name: ff.field_name(:email), value: ff.object.email, type: :email, class: 'base-input', multiple: true, autocomplete: 'off', placeholder: t('default_email'), disabled: ff.object.is_requester || ff.object.invite_by_uuid.present? || ff.object.optional_invite_by_uuid.present?, id: field_uuid = SecureRandom.uuid %> + <% else %> + + <%= ff.select :option, [[t('not_specified'), 'not_set'], [t('submission_requester'), 'is_requester'], [t('specified_email'), 'email'], *(template.submitters - [submitter]).flat_map { |e| [[t('invite_by_name', name: e['name']), "invite_by_#{e['uuid']}"], [t('invite_by_name', name: e['name']) + " (#{t(:optional).capitalize})", "optional_invite_by_#{e['uuid']}"]] }, *(template.submitters - [submitter]).map { |e| [t('same_as_name', name: e['name']), "linked_to_#{e['uuid']}"] }], {}, class: 'base-select mb-3' %> + + <%= tag.input name: ff.field_name(:email), type: :email, value: ff.object.email, multiple: true, class: "base-input #{'hidden' if item.option != 'email'}", autocomplete: 'off', placeholder: t('default_email'), id: email_field_uuid %> + <% end %> +
+ <% if template.submitters.size == 2 %> + + + <% if index == 1 %> + + <% end %> + + <% end %> + <% end %> +
+ <% end %> +
+<% end %> +<% unless current_account.account_configs.exists?(key: AccountConfig::ENFORCE_SIGNING_ORDER_KEY, value: true) %> + <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> +
+ + <%= t('enforce_recipients_order') %> + + <%= f.fields_for :preferences, Struct.new(:submitters_order).new(template.preferences['submitters_order']) do |ff| %> + <%= ff.check_box :submitters_order, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'preserved', '' %> + <% end %> +
+ <% end %> +<% end %> +<% if can?(:manage, :personalization_advanced) %> + <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> +
+ + <%= t('ensure_unique_recipients') %> + + <%= f.fields_for :preferences, Struct.new(:validate_unique_submitters).new(template.preferences['validate_unique_submitters']) do |ff| %> + <%= ff.check_box :validate_unique_submitters, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'true', '' %> + <% end %> +
+ <% end %> +<% end %> +
+ <%= button_tag button_title(title: t('save'), disabled_with: t('updating')), class: 'base-button', form: :submitters_form %> + <% unless close_on_submit %> +
+ +
+ <% end %> +
diff --git a/app/views/templates_preferences/show.html.erb b/app/views/templates_preferences/show.html.erb index 165def27..5d7cb397 100644 --- a/app/views/templates_preferences/show.html.erb +++ b/app/views/templates_preferences/show.html.erb @@ -287,91 +287,8 @@ <%= render 'templates_code_modal/preferences', class: 'pt-2' %>
<% if show_recipients %> - <% end %> -<% unless current_account.account_configs.exists?(key: AccountConfig::ENFORCE_SIGNING_ORDER_KEY, value: true) %> - <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> -
- - <%= t('enforce_recipients_order') %> - - <%= f.fields_for :preferences, Struct.new(:submitters_order).new(template.preferences['submitters_order']) do |ff| %> - <%= ff.check_box :submitters_order, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'preserved', '' %> - <% end %> -
+<% if local_assigns[:with_toggles] != false %> + <% unless current_account.account_configs.exists?(key: AccountConfig::ENFORCE_SIGNING_ORDER_KEY, value: true) %> + <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> +
+ + <%= t('enforce_recipients_order') %> + + <%= f.fields_for :preferences, Struct.new(:submitters_order).new(template.preferences['submitters_order']) do |ff| %> + <%= ff.check_box :submitters_order, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'preserved', '' %> + <% end %> +
+ <% end %> <% end %> -<% end %> -<% if can?(:manage, :personalization_advanced) %> - <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> -
- - <%= t('ensure_unique_recipients') %> - - <%= f.fields_for :preferences, Struct.new(:validate_unique_submitters).new(template.preferences['validate_unique_submitters']) do |ff| %> - <%= ff.check_box :validate_unique_submitters, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'true', '' %> - <% end %> -
+ <% if can?(:manage, :personalization_advanced) %> + <%= form_for template, url: template_preferences_path(template), method: :post, html: { autocomplete: 'off', class: 'mt-2' }, data: { close_on_submit: false } do |f| %> +
+ + <%= t('ensure_unique_recipients') %> + + <%= f.fields_for :preferences, Struct.new(:validate_unique_submitters).new(template.preferences['validate_unique_submitters']) do |ff| %> + <%= ff.check_box :validate_unique_submitters, { class: 'toggle', onchange: 'this.form.requestSubmit()' }, 'true', '' %> + <% end %> +
+ <% end %> <% end %> <% end %>
diff --git a/app/views/templates_share_link/show.html.erb b/app/views/templates_share_link/show.html.erb index 4cb36ba4..f6abafc4 100644 --- a/app/views/templates_share_link/show.html.erb +++ b/app/views/templates_share_link/show.html.erb @@ -1,10 +1,10 @@ <%= render 'shared/turbo_modal_large', title: t('share_link') do %>
<%= form_for @template, url: template_share_link_path(@template), method: :post, html: { id: 'shared_link_form', autocomplete: 'off', class: 'mt-3' }, data: { close_on_submit: false } do |f| %> -
- <%= t('enable_shared_link') %> +
+
@@ -12,7 +12,7 @@
<% end %> - <%= form_for @template, url: template_preferences_path(@template), method: :post, html: { autocomplete: 'off', class: 'mt-3' }, data: { close_on_submit: false } do |f| %> + <%= form_for @template, url: template_preferences_path(@template), method: :post, html: { autocomplete: 'off', class: 'mt-4 mb-5' }, data: { close_on_submit: false } do |f| %> <% link_form_fields = @template.preferences.fetch('link_form_fields', ['email']) %> @@ -31,13 +31,13 @@
<% end %> <% if @template.submitters.to_a.length > 1 %> -
+
- <%= t('recipients') %> + <%= t('default_parties') %>
- <%= render 'templates_preferences/recipients', template: @template, close_on_submit: false %> + <%= render 'templates_preferences/recipients', template: @template, close_on_submit: false, with_toggles: false, with_submission_requester: false %>
<% end %> diff --git a/config/locales/i18n.yml b/config/locales/i18n.yml index 48443542..d1999566 100644 --- a/config/locales/i18n.yml +++ b/config/locales/i18n.yml @@ -22,6 +22,7 @@ en: &en hi_there: Hi there thanks: Thanks private: Private + default_parties: Default parties authenticate_embedded_form_preview_with_token: Authenticate embedded form preview with token stripe_integration: Stripe Integration require_all_recipients: Require all recipients @@ -761,7 +762,7 @@ en: &en review_or_download_completed_documents_fill_and_sign_documents_online_effortlessly_with_a_secure_fast_and_user_friendly_digital_document_signing_solution: Review or download completed documents. Fill and sign documents online effortlessly with a secure, fast, and user-friendly digital document signing solution. link_form_fields: Link form fields at_least_one_field_must_be_displayed_in_the_form: At least one field must be displayed in the form. - this_template_has_multiple_parties_which_prevents_the_use_of_a_sharing_link: This template has multiple parties, which prevents the use of a sharing link as it's unclear which party is responsible for specific fields. To resolve this, define the default party details. + this_template_has_multiple_parties_which_prevents_the_use_of_a_sharing_link: This template has multiple parties, which prevents the use of a shared link as it's unclear which party is responsible for specific fields. To resolve this, define the default party details. submission_sources: api: API bulk: Bulk Send @@ -864,6 +865,7 @@ en: &en range_without_total: "%{from}-%{to} items" es: &es + default_parties: Partes predeterminadas authenticate_embedded_form_preview_with_token: Autenticar vista previa del formulario incrustado con token require_all_recipients: Requerir a todos los destinatarios stripe_integration: Integración con Stripe @@ -1709,6 +1711,7 @@ es: &es range_without_total: "%{from}-%{to} elementos" it: &it + default_parties: Parti predefiniti authenticate_embedded_form_preview_with_token: "Autentica l'anteprima del modulo incorporato con il token" require_all_recipients: Richiedi tutti i destinatari stripe_integration: Integrazione Stripe @@ -2552,6 +2555,7 @@ it: &it range_without_total: "%{from}-%{to} elementi" fr: &fr + default_parties: Parties par défaut authenticate_embedded_form_preview_with_token: Authentifier l’aperçu du formulaire intégré avec un jeton require_all_recipients: Exiger tous les destinataires stripe_integration: Intégration Stripe @@ -3398,6 +3402,7 @@ fr: &fr range_without_total: "%{from} à %{to} éléments" pt: &pt + default_parties: Partes padrão authenticate_embedded_form_preview_with_token: Autenticar visualização incorporada do formulário com token require_all_recipients: Exigir todos os destinatários stripe_integration: Integração com Stripe @@ -4244,6 +4249,7 @@ pt: &pt range_without_total: "%{from}-%{to} itens" de: &de + default_parties: Standardparteien authenticate_embedded_form_preview_with_token: Authentifizieren Sie die eingebettete Formularvorschau mit Token require_all_recipients: Alle Empfänger erforderlich stripe_integration: Stripe-Integration From 10e4476f4ab8923ab0622b5a980147cc94fcc3c9 Mon Sep 17 00:00:00 2001 From: Pete Matsyburka Date: Mon, 30 Jun 2025 11:41:07 +0300 Subject: [PATCH 26/27] fix signature prefill --- app/javascript/submission_form/initials_step.vue | 5 ++++- app/javascript/submission_form/signature_step.vue | 6 ++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/app/javascript/submission_form/initials_step.vue b/app/javascript/submission_form/initials_step.vue index fe36db8f..376fb7e9 100644 --- a/app/javascript/submission_form/initials_step.vue +++ b/app/javascript/submission_form/initials_step.vue @@ -203,7 +203,7 @@ export default { emits: ['attached', 'update:model-value', 'start', 'minimize', 'focus'], data () { return { - isInitialsStarted: !!this.previousValue, + isInitialsStarted: false, isUsePreviousValue: true, isDrawInitials: false, uploadImageInputKey: Math.random().toString() @@ -218,6 +218,9 @@ export default { } } }, + created () { + this.isInitialsStarted = !!this.computedPreviousValue + }, async mounted () { this.$nextTick(() => { if (this.$refs.canvas) { diff --git a/app/javascript/submission_form/signature_step.vue b/app/javascript/submission_form/signature_step.vue index 0b09e8cf..d1625726 100644 --- a/app/javascript/submission_form/signature_step.vue +++ b/app/javascript/submission_form/signature_step.vue @@ -201,7 +201,7 @@
Date: Mon, 30 Jun 2025 11:44:55 +0300 Subject: [PATCH 27/27] fix sqlite remove template --- app/models/submission.rb | 2 +- app/models/submitter.rb | 2 +- app/models/template.rb | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/app/models/submission.rb b/app/models/submission.rb index 002933e5..4e61c691 100644 --- a/app/models/submission.rb +++ b/app/models/submission.rb @@ -40,7 +40,7 @@ class Submission < ApplicationRecord belongs_to :account belongs_to :created_by_user, class_name: 'User', optional: true - has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy + has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy if SearchEntry.table_exists? has_many :submitters, dependent: :destroy has_many :submission_events, dependent: :destroy diff --git a/app/models/submitter.rb b/app/models/submitter.rb index b684dfbe..205a3b0c 100644 --- a/app/models/submitter.rb +++ b/app/models/submitter.rb @@ -43,7 +43,7 @@ class Submitter < ApplicationRecord belongs_to :submission belongs_to :account has_one :template, through: :submission - has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy + has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy if SearchEntry.table_exists? attribute :values, :string, default: -> { {} } attribute :preferences, :string, default: -> { {} } diff --git a/app/models/template.rb b/app/models/template.rb index 41b635a0..59f2c36d 100644 --- a/app/models/template.rb +++ b/app/models/template.rb @@ -44,7 +44,7 @@ class Template < ApplicationRecord belongs_to :account belongs_to :folder, class_name: 'TemplateFolder' - has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy + has_one :search_entry, as: :record, inverse_of: :record, dependent: :destroy if SearchEntry.table_exists? before_validation :maybe_set_default_folder, on: :create