CHANGELOG.md

4.4.0 [November 1, 2026]

• New: list_email_actions, create_email_action, get_email_action, update_email_action and delete_email_action manage a template's email actions (EmailAction), which email each processed submission's files as attachments or a download link. to, cc and bcc take addresses, and tags for an address in the submission's fields ({{ data.client_email }}) or metadata ({{ metadata.agent_email }}). send_when sends only for the submissions that meet its conditions. file_name names the attached files, and file_formats chooses them: a Word template's Word document (docx), OpenDocument file (odt) or PDF (pdf), or every file the submission made (all). Attached files over max_attachment_mb together (7 MB unless you raise it, up to 25) go as a link instead. send_email_action_test_email sends one to you to check how it looks (EmailActionTestEmail). Without a paid plan (Starter or higher), email actions only email your team: test emails, and test submissions' emails.
• New: list_account_email_actions, create_account_email_action, get_account_email_action, update_account_email_action and delete_account_email_action manage your account's email actions, which send for every template, or for the templates and folders they list (template_ids, folder_ids). send_account_email_action_test_email sends one to you for one of its templates.
• New: list_email_actions also lists your account's email actions that send for the template, with the template's changes in customization (EmailActionCustomization). update_email_action_customization changes one for that template only, or turns it off there (enabled), and delete_email_action_customization removes the template's changes.
• New: list_email_domains, create_email_domain, get_email_domain, verify_email_domain and delete_email_domain manage the domains your email actions send from (EmailDomain), with the DNS records to add to each one (EmailDomainDnsRecord).
• A submission's actions include the emails its email actions sent (its template's and your account's), with each recipient and what happened to their email, and a new email_action_id.
• New: a field's string_condition_type can be not_equals, not_contains, not_starts_with, not_ends_with, not_regex, blank or not_blank, and a regex condition uses RE2 syntax (no lookarounds or backreferences).
• create_submission: DocSpring now emails the signers of a submission's signature_requests a link to sign, any reminders, and the signed PDF once everyone has signed. Set send_email to false, for the submission or for one signature request, when you send the links yourself or show the signing form in your app. A signature request that DocSpring emails needs an email, and its auth_type is optional (email_link). Before anyone is emailed, the request can be refused with a 402 (insufficient_credits_to_send), a 403 or a 429 (daily_email_limit_reached), and nothing is saved.
• New create_submission properties for these emails: signing_order (SigningOrder) with each signature request's signing_step, email_subject, email_message, cc, reply_to, notification_emails, notify_when_signed and reminders (SignatureRequestReminders).
• A signature request has send_email, signing_step, sent_at and email_status (SignatureRequestEmailStatus), and a submission has signing_order.
• Templates have new settings for these emails: signature_request_from_name, signature_request_from_address, signature_request_signing_url, signature_request_include_signing_token, signature_request_reply_to, signature_request_notification_emails and signature_request_email_attachments (SignatureRequestEmailAttachments).
• New webhook event types: signature_request.sent and signature_request.email_bounced.
• New: page designs (template_type page_designer), PDFs designed in the Page Designer from a JSON layout, with no document to start from. create_template makes one from its layout, or with an empty page when layout is left out, and update_template replaces its layout. DocSpring adds a field for each value the layout reads. A template's layout is in the Page Designer layout format (its JSON Schema), and is null for other templates.
• New: every method that creates, changes or deletes something takes an Idempotency-Key header, as the idempotencyKey option. Send the same key when you send a request again after a timeout or a network error: within 24 hours, DocSpring returns the first response instead of running the request twice. Arguments you already pass keep their places.
• Changed: the request validator checks what API v2 now refuses: an ID, a query value or a template name that's blank or only whitespace, an update with nothing to change, a version with a leading zero (01), a filename with a slash, a signer email that isn't an email address, and an HTML template's scale outside 0.1 to 2.
• New: get_template_model_code takes rust as its lang, for Rust structs that serde reads and writes.

4.3.0 [October 31, 2026]

• New: get_template_model_code takes rust as its lang, for Rust structs that serde reads and writes.
• New: Word templates (template_type docx). create_template makes one from a Word document (.docx, up to 50 MB) that you upload and pass as a cache_id, or pass as a document_url or document_base64; upload_template takes the file itself. update_template_document and upload_template_document replace its document the same ways. Each tag in the document, such as {{ customer.name }}, becomes a field. Each of them takes an OpenDocument text file (.odt) too, which DocSpring converts to a Word document.
• New: a Word template's output_format, what its submissions make unless they set output_formats: docx (a Word document), odt (an OpenDocument file) or pdf. create_template and upload_template require it, and update_template changes it. A Word template that encrypts its PDFs makes PDFs, because Word documents and OpenDocument files can't be password-protected.
• New: the docx and odt output formats, a Word template's filled-in Word document (files.docx) and OpenDocument file (files.odt, converted from the Word document). Add them to output_formats in create_submission or create_submission_batch to get more than one file, such as the Word document and the PDF.
• generate_submission_files takes pdf, the PDF of a Word template's submission that didn't make one (converted from its Word document), docx, the Word document of one that made only its PDF (made again from its data and the template version it used), and odt, its OpenDocument file. None of them uses credits again. Until the new file is ready, its state in files is pending, and when it couldn't be made, its error_message says why.
• A Word template's document is its Word document: document.permanent_url downloads it. Its state is processed once it's uploaded or downloaded (downloading or download_failed while a document_url downloads, converting or conversion_failed while an OpenDocument file is converted), and get_template_diff's document_changed says whether it was edited.
• get_template_page_images returns a 409 for a Word template, whose pages are only laid out when a document is made.
• create_template_preview previews Word templates too: images of the pages of the PDF that the template's Word document makes with your data. A DocSpring server that can't convert Word documents to PDF returns a 409.

4.2.0 [October 29, 2026]

• BREAKING CHANGE: list_templates returns a shorter TemplateSummary: a template's name, description, type, folder (parent_folder_id, path), latest published version, whether it's ready, and its PDF's file name, state, error and page count (document, a TemplateDocumentSummary). get_template returns its settings and the rest.
• BREAKING CHANGE: list_submissions and list_template_submissions return SubmissionSummary instead of Submission: without signature requests and uploads, with data only when you pass include_data (as before), and with files only when you pass the new include_files (without the links to page images). get_submission returns the whole submission.
• New: the template webhook events (version 4) send the whole template, as get_template returns it, without its embed_edit_token. They sent the settings without the rest.
• New: list_submissions and list_template_submissions take a state filter: one state, such as invalid_data or error.
• New: get_template_model_code takes just_types, for the types alone, without the code that converts and checks JSON (TypeScript, Ruby, Python, Java, C#, Elixir and Go: JavaScript and PHP code is the same either way).
• New: create_submission, create_submission_batch and create_combined_pdf take an Idempotency-Key header. A request repeated with the same key within 24 hours returns the first response and creates nothing. The same key with a different request is a 422, and a repeat while the first request is still running is a 409.
• New: create_template_preview and get_template_preview fill an HTML or PDF template's draft (or a published version) with your data and return PNG images of its pages, not a PDF, so you can check how it prints before you publish it or send live data. A preview creates no submission and uses no credits. Get the preview until its state is processed. Previews are watermarked like test PDFs.
• New: HTML templates' html_escape_data setting HTML-escapes the values they print ({{ value }}). It's on for new templates and off for existing ones; {{ value | raw }} prints a value as it is.
• New: verifyWebhookSignature(payload, signatureHeader, secret) checks a webhook request's X-DocSpring-Signature header. Pass it the request body exactly as it was received. It returns true or false, accepts any v1 that matches and rejects a timestamp more than 5 minutes old ({ tolerance } for another tolerance).
• publish_template_version answers 409 when the draft hasn't changed since the latest published version, instead of publishing a copy of it (code conflict). A template's first publish always works.
• Every operation documents the 429 rate limit response (with Retry-After), and the creates that the sync hosts wait for document their 504 (the record was saved: get it by the ID in the error).
• Every optional field takes null in a submission's data, whatever its type, so model code that writes missing values as null works. A null checkbox or group of fields (an object or a list) gets its defaults, as a missing key does, and a null text, number, date, image or signature field prints blank, as before. Null in a required field is still an error.
• Template and webhook names can be up to 512 characters, up from 255.

4.1.0 [October 27, 2026]

• New: list_template_fields, add_template_fields, update_template_fields, remove_template_fields and reorder_template_fields read and edit a template's fields (Field), with all their settings and their own conditional logic (dependencies). A field's y is measured from the top of its page.
• New: a template's predefined_fields (PredefinedField) and predefined_fields_sample_data, the field names that people using the embedded template editor choose from. get_template returns them, and create_template and update_template set them.
• New: a template's field_groups (FieldGroup), the groups that its fields' names make, with their titles and the settings of lists (min_items, max_items, allow_additional_items). get_template returns them, and update_template changes them.
• New: get_template_page_images returns an image of each page of a PDF template (TemplatePageImages), to see where fields go.
• New: get_template_diff says what changed in a template's draft since its latest published version, or in a published version since the one before it (TemplateDiff).
• New: validate_submission checks a submission's data and settings as create_submission does, without creating the submission or using credits (SubmissionValidation). It doesn't check your account's credits.
• New: the png output format, an image of each page of a submission's PDF (files.png.pages). Add it to output_formats in create_submission or create_submission_batch (it adds pdf), or to a processed submission with generate_submission_files.
• create_template and update_template_document take a document_url (DocSpring downloads it) or a document_base64 instead of a cache_id. While the URL downloads, the template's document.state is downloading; if it can't be downloaded, it's download_failed and document.error_message says why.
• BREAKING CHANGE: cache_id is one of three ways to send update_template_document's document, so it's optional: new UpdateTemplateDocumentRequest() takes no arguments, and a cache ID passed to it is ignored. Set cache_id on the object, or send a plain object ({ cache_id: 'cache/...' }).

4.0.0 [October 26, 2026]

• BREAKING CHANGE: This version calls DocSpring API v2 (/api/v2). The 3.x versions call API v1, which keeps working. Every change is in the migration guide: https://docspring.com/docs/api-guide/migrating-to-api-v2/
• BREAKING CHANGE: If you set the API's full base URL yourself, change /api/v1 in it to /api/v2. The client only picks the version in the URLs it builds from a region or host.
• BREAKING CHANGE: Operations are named after the resource they act on. generate_pdf is create_submission, batch_generate_pdfs is create_submission_batch, combine_pdfs is create_combined_pdf, create_html_template and create_pdf_template_from_upload are create_template (with a template_type), create_pdf_template (which uploads a PDF file) is upload_template, get_full_template is get_template (which returns the template, without its fields for now), update_template_document (which uploads a PDF file) is upload_template_document, update_template_document_from_upload is update_template_document, generate_preview is generate_submission_preview, get_combined_submission is get_combined_pdf, list_combined_submissions is list_combined_pdfs, expire_combined_submission is expire_combined_pdf, move_template_to_folder is move_template and move_folder_to_folder is move_folder. New: get_folder, list_custom_files, get_custom_file and delete_custom_file. A template's fields, and adding fields to a template, aren't in API v2 yet.
• BREAKING CHANGE: Data requests are called signature requests. get_data_request, update_data_request, create_data_request_token and create_data_request_event are get_signature_request, update_signature_request, create_signature_request_token and create_signature_request_event (at /signature_requests), and their models are SignatureRequest, SignatureRequestToken and SignatureRequestEvent. A submission's data_requests is signature_requests (also when you create one), data_request_id is signature_request_id, a token's data_request_url is signature_request_url, the waiting_for_data_requests state is waiting_for_signature_requests, and a template's add_data_request_submission_id_footers is add_signature_request_submission_id_footers. New ones get IDs that start with srq_ instead of drq_.
• BREAKING CHANGE: A response is the resource itself, with no status or wrapper key. Lists return data and next_cursor: pass next_cursor as cursor to get the next page, and limit (1 to 100, default 50) for its size. page and per_page are gone. Every create returns 201.
• BREAKING CHANGE: Every error has one shape, {"error": {"code", "message", "details", "request_id"}}, with a code to check (validation_failed, not_found, insufficient_credits, rate_limited, ...), and each detail has a pointer to the body value it's about, or a parameter with the query parameter's name.
• BREAKING CHANGE: Requests are validated strictly: an unknown property or query parameter, or a value of the wrong type, is a 422 instead of being ignored. Request bodies must be JSON (Content-Type: application/json, or it's a 415), except the PDF uploads. Request bodies are flat, with no template, folder or webhook key around them.
• BREAKING CHANGE: Submission data is checked more strictly. An empty data is validated like any other, date fields take YYYY-MM-DD (or the template's date format when parse_dates_using_template_date_format is on), and a signature request's fields must be fields on the template (set ignore_unknown_fields to leave out the others). A submission that fails because of the template is still saved as invalid_data, and the 422 includes its submission_id.
• BREAKING CHANGE: A submission's or combined PDF's files are in files, by format. files.pdf has state, error_message, download_url, permanent_url, filename, content_type, size and sha256, and replaces download_url, permanent_download_url and pdf_hash. A submission's files.audit_trail and files.preview, with the same properties, replace audit_trail_download_url and preview_download_url. A file made after its submission was processed is listed while it's being made, so check its state before using its links. Combined submissions are combined PDFs (CombinedPdf), a template's document_url is document.download_url, and a custom file's url is download_url.
• BREAKING CHANGE: A template's embed_domains is a list of domains, not a comma-separated string, and each entry is checked. Copying a template with parent_folder_id null puts the copy at the root (leave it out to keep the template's folder). A template's schema and model code describe the version that submissions use by default (the latest published version), not the draft: pass version for another one.
• BREAKING CHANGE: Every property name is snake_case, including template defaults (font_size, was fontSize), html_engine_options (margin_top), a field dependency condition's range_max, and the field settings in a submission's field_overrides.
• field_overrides takes a FieldOverride per field name, with every setting an override can change (required, font_size, color, ...), so a misspelt setting or a value of the wrong type is caught before the request is sent.
• A combined PDF's source_pdfs and a rule's conditions take a model per kind, with only the properties that kind uses (another kind's property is a 422 not_allowed). CombinedPdfSourceInput is a SubmissionSourcePdf, CombinedPdfSourcePdf, TemplateSourcePdf, CustomFileSourcePdf or UrlSourcePdf, picked by its type. TemplateFieldDependencyConditionInput is a FieldPresenceCondition (present, blank), FieldEqualsCondition (equals, not_equals), FieldInCondition (in, with a list), FieldComparisonCondition (gt, gte, lt, lte, on a number field) or FieldRangeCondition (range), picked by its operator. Pass plain objects: { type: 'url', url }. A template returns its conditions with only the properties their operators use, in the shape an update takes.
• BREAKING CHANGE: Templates: ready and a document object (with its state, page_count and page_dimensions) replace document_processed, document_state, document_parse_error and the page_* fields. list_templates returns template summaries. Templates have no webhook_url or webhook_options: create a webhook with template_ids instead.
• BREAKING CHANGE: Secrets are write-only. A submission's or combined PDF's password and a template's encrypt_pdfs_password and slack_webhook_url aren't returned; has_password, has_encrypt_pdfs_password and has_slack_webhook_url say whether one is set.
• BREAKING CHANGE: Webhooks created with this version send payload version 4, {"id", "event_type", "created_at", "data"}, where data is the resource as API v2 returns it. Their events have API v2's names (combined_pdf.processed, signature_request.completed). Webhooks created with 3.x or in the dashboard keep their payload version.
• BREAKING CHANGE: Models are named after the API's resources (Submission, CombinedPdf, Template, TemplateSummary, SignatureRequest), request bodies after their operation (CreateSubmissionRequest), and enums are their own types (SubmissionState, WebhookEventType).
• Enum types have static constants (SubmissionState.processed): they were instance fields, so only new SubmissionState().processed had the value. Values are plain strings, so a value added to the API after this release comes back as it came.
• The client checks each request against the API's request schemas before sending it, so an invalid request fails without a round trip, with the details the API's 422 response would have. A request the API would reject fails with a ValidationError (exported by the package), whose details are objects with code, message and a pointer into the body (or a parameter). Turn the check off with client.apiClient.validateRequests = false.
• A waited request to sync.api.docspring.com that times out returns a 504 polling_timeout error with the resource's ID, so you can get it later. Without an ID, the request got no answer in time: check whether the resource was created before you send it again.
• BREAKING CHANGE: Every operation returns a promise that you can await, instead of taking a callback.
• BREAKING CHANGE: A rejected call's response, like the response a ...WithHttpInfo method returns, is an object with the response's status, statusText, headers, body and text. It was superagent's response, which also held the request and its Authorization header, so logging the error (console.log, JSON.stringify) printed your API token. The superagent error in error no longer has the response either.
• BREAKING CHANGE: A client created with credentials, a host or a region has its own ApiClient, so two clients with different credentials or hosts no longer change each other's, and settings made on ApiClient.instance don't apply to it. new DocSpring.Client() with no options still uses ApiClient.instance. Pass apiClient to share one.
• An empty API token ID or secret counts as not set, so the client reads DOCSPRING_TOKEN_ID or DOCSPRING_TOKEN_SECRET instead. It was sent as an empty string.
• Templates: new default_form_mode setting (web, visual or dual), when you create or update a template. It's the hosted form that /templates/<id>/form opens when the link has no mode parameter: the web form, the visual form (filled in on the PDF), or both in tabs. HTML templates have no visual form, so they only accept web.
• Templates: defaults can set required_field_background_color, the background colour that visual forms and signature requests give required fields. PDFs don't draw it.
• Templates: new allow_skipping_optional_fields setting (boolean), when you create or update a template. Visual forms and signature requests then show the Continue button as soon as the required fields are filled in, without visiting each optional field. The allowSkippingOptionalFields embed option overrides it.
• Templates: when you replace a template's PDF, reimport_fields (boolean) replaces the template's fields with the fillable fields in the new PDF (or in its current PDF when you don't upload one). A PDF with no fillable fields keeps the template's fields.
• Fields: shape_type can be triangle or polygon, with shape_sides (3 to 12) for a polygon. Text fields can set keep_leading_spaces to keep the spaces at the start of each line in the PDF.
• Templates: create_template and upload_template take detect_fields (boolean, default false). DocSpring then sets up the PDF's fields as the "Automatically detect fields" upload option does: it imports or detects them, names them with AI and sets up conditional logic. field_source (auto, pdf_detection or pdf_form_fields), field_naming (ai or preserve) and field_logic (ai or none) choose how, like the Set Up Fields choices in the template editor. With pdf_form_fields, preserve and none, the PDF's form fields are imported with their own names and no AI. Each account gets free AI pages every month, and further pages are paid from credits. See https://docspring.com/docs/template-editor/automatic-field-detection/.
• Templates: new ai_field_naming_language setting (auto, english or form_language) for PDF templates, when you create or update one: the language AI uses for field names. It's null for HTML templates.
• Templates: a template's document includes has_fillable_fields, page_processing_statuses (how processing is going on each page: its image, its fields and AI naming) and field_logic_status (the AI logic step that runs once every page's fields are done, and can still rename fields and add rules). Field setup is finished when document.state is processed and field_logic_status isn't pending or processing.

3.3.0 [October 18, 2026]

• Submissions and combined submissions can be in the new insufficient_credits state: a live PDF that your credit balance can't cover is saved and processed once you add credits. See https://docspring.com/docs/api-guide/credits-and-rate-limits/.
• generate_pdf, batch_generate_pdfs and combine_pdfs document the 402 response for insufficient credits. Their responses can include a code, which is insufficient_credits on a 402.
• generate_pdf, batch_generate_pdfs, create_pdf_template, create_pdf_template_from_upload, create_html_template and copy_template document a 403 response with a code of upgrade_required (the plan doesn't include it) or account_suspended.

3.2.0 [October 18, 2026]

• Response models keep fields this version doesn't know as properties of the model object.
• Templates: new parse_dates_using_template_date_format setting, when you create or update a template. When it's true, date values sent as NN/NN/YYYY (with slashes, dashes or dots) are read in the order of the template's default date format: month first for %m/%d/%Y, day first for %d/%m/%Y. When it's false, they're read day first.
• A new README: installing, a quick start, every API method, errors, and how API changes are handled. The repository also has an AGENTS.md for coding agents.

3.1.0 [October 15, 2026]

• Submissions and data requests can now be in the declined state, when a signer declines to sign. Data requests have a new declined_at timestamp.
• New API methods for webhooks: create_webhook, list_webhooks, get_webhook, update_webhook and delete_webhook.
• New API method: get_template_model_code, which generates typed model code for a template's submission data, so your app can catch mistakes before it calls the API.
• Templates:
  • Field dependencies: field_dependencies when you create or update a template, and dependencies on the fields you add with add_fields_to_template.
  • add_fields_to_template accepts the initials field type and an editable setting for each field.
  • Embedded template editor settings: embed_edit_allow_document_replacement, embed_edit_allow_settings, embed_edit_allow_versioning and embed_edit_token.
  • New template_schema_version attribute.
  • A template's path is never null.
  • Individual template defaults can be null (for example fontSize after it's cleared in the template editor).
  • last_changed_by_type can be external_user (a change made in the embedded template editor), with last_changed_by_external_id, last_changed_by_external_name and last_changed_by_external_email.
  • Template versions say who published them with published_by_type, published_by_user_id, published_by_name, published_by_email and published_by_external_id. These replace published_by_id, which the API no longer returns.
  • The JSON schema from get_template_schema includes $id, allOf and dependencies.
• copy_template accepts a template version, and parent_folder_id is now optional. move_template_to_folder also accepts a version.
• Pass a null parent_folder_id to move_template_to_folder or move_folder_to_folder to move it to the root folder.
• Submissions and submission actions include an error_message when processing fails.
• combine_pdfs: delete_custom_files now deletes the custom files once the merged PDF is processed (it used to be ignored). test has no effect and is deprecated.
• The package metadata declares the MIT license, like the LICENSE file (it said Unlicense).
• The host option and DOCSPRING_HOST can end with /api/v1/ or have spaces around them (a trailing slash after /api/v1 sent requests to paths with //).

3.0.0 [September 24, 2025]

• All our API clients are now 100% end-to-end tested against our real server.

2.1.0 [March 22, 2025]

• Added support for Template Versioning parameters:
  • Optional version parameter in submission requests (e.g., 1.2.3, draft, latest)
  • New API methods: publish_template_version, restore_template_version
  • Updated copy_template and delete_template methods to accept template version strings

2.0.0 [February 23, 2025]

• BREAKING CHANGE: Updated default host to our new synchronous API subdomain: sync.api.docspring.com. (EU customers should use sync.api-eu.docspring.com). Removed all custom polling code from library since this logic is now handled by the API service running on our sync subdomain
• Fixed User-Agent header: docspring-javascript-x.x.x

1.5.0 [August 30, 2023]

• Added Delete Template API endpoint

1.4.0 [March 22, 2022]

• Renamed "Template1" model to "FullTemplate" since it includes all properties

1.3.2 [November 28, 2021]

• Added 'password' parameter to Generate PDF and Combine PDF API endpoints. You can now encrypt each generated PDF with a unique password.

1.3.1 [November 19, 2020]

• Added "sort_order" property for Submission Data Requests

1.3.0 [September 26, 2020]

• Updated OpenAPI Generator to v3.3.0

1.2.1 [September 24, 2020]

• Fixed the "include_data=true" option for the "Get Submission" API endpoint. Added the "data" property to the Submission model so that this is parsed and returned correctly when requested

1.2.0 [September 21, 2020]

• Renamed some internal models for template creation API endpoints. (CreateTemplateData / CreateTemplateData1 renamed to CreateHtmlTemplateData and CreateTemplateFromUploadData)

1.1.0 [September 12, 2020]

• BREAKING CHANGE: Renamed createTemplate operation to createPDFTemplate
• Added createHTMLTemplate operation. (This uses the same API endpoint as createPDFTemplate, but the example shows how to set html, scss, etc. fields)
• Added updateTemplate operation, to update a PDF or HTML template

1.0.0 [May 20, 2019]

• Renamed FormAPI to DocSpring. (View the CHANGELOG in the original FormAPI API client for prior releases.)