Skip to content

CHANGELOG.md

Latest commit

 

History

History
262 lines (231 loc) · 20.8 KB

CHANGELOG.md

File metadata and controls

262 lines (231 loc) · 20.8 KB
Raw

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.

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.
  • BREAKING CHANGE: field_overrides takes a FieldOverride per field name (Map<String, FieldOverride>), 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.
  • BREAKING CHANGE: 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 the model to the union's constructor; a model sets its own type (and FieldInCondition and FieldRangeCondition their operator): new CombinedPdfSourceInput(new UrlSourcePdf().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).
  • BREAKING CHANGE: Enum types are final classes instead of Java enums, so they can hold a value added to the API after this release. The constants (SubmissionState.PROCESSED) are the values this version knows, getValue() returns the value as the API sent it, isKnown() is false for a newer one, fromValue keeps any value, values() lists the known ones, and equality is by value. A switch on one needs getValue(). UNKNOWN_DEFAULT_OPEN_API is gone.
  • 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 throws a com.docspring.ValidationException (an IllegalArgumentException), whose getDetails() are ErrorDetails with a code, a message and a pointer into the body (or a parameter). Turn the check off with apiClient.setValidateRequests(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.
  • Lists you don't set are left out of requests instead of being sent as empty lists.
  • BREAKING CHANGE: URLs are Strings instead of java.net.URI, which couldn't hold every URL the API returns. Free-form objects (data, metadata) are Map<String, Object>, and lists of unique values are Sets.
  • Depends on Jackson 2.21 (was 2.17) and jackson-databind-nullable 0.2.12.
  • 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.
  • Java: createPdfTemplate (multipart) takes the new detect_fields, field_source, field_naming, field_logic and ai_field_naming_language form fields as its last five arguments, so existing calls need five more arguments (null to leave them out).

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: read them with getAdditionalProperties().
  • In an enum that can be null (such as a webhook's mode), a value this version doesn't know now reads as UNKNOWN_DEFAULT_OPEN_API instead of null.
  • 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. Earlier versions raise an error when they read a declined submission or data request.
  • 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.
  • new Client() reads DOCSPRING_TOKEN_ID, DOCSPRING_TOKEN_SECRET, DOCSPRING_HOST and DOCSPRING_REGION (US or EU) from the environment, for any credentials or host not already set on the default ApiClient. New constructors: Client(apiTokenId, apiTokenSecret) and Client(apiTokenId, apiTokenSecret, host, region).
  • An enum value added to the API after this release (e.g. a new submission state) deserializes as UNKNOWN_DEFAULT_OPEN_API instead of throwing, or as null for an attribute that can be null. Enums have the new UNKNOWN_DEFAULT_OPEN_API constant, so an exhaustive switch over one needs a case for it.
  • source, referrer and data are optional on submissions, because get_submission, list_submissions and list_template_submissions only return them with include_data. getSource() is now @Nullable.

3.0.1 [September 24, 2025]

  • Accidentally had a hard-coded 2.x version in the user agent string for v3.0.0

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-java-x.x.x

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.
  • Fixed MultipartBody.Part annotation issue for createPDFTemplate. Added Java code example to docs.

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