CHANGELOG.md

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.)