Generate PDFs via API
DocSpring generates PDFs by filling your templates with submission data. Templates can either be uploads that you annotate in the Template Editor or fully custom HTML/CSS layouts that you host in DocSpring.
Endpoint
Section titled “Endpoint”POST /api/v1/templates/{template_id}/submissionsRequest Payload Basics
Section titled “Request Payload Basics”Every submission must include:
data— Field values that match your template schema.test— Usetruefor free, watermarked PDFs while building your integration.metadata— Optional map for values you want echoed back in webhooks.version— Choosedraft,latest, or a specific version such as1.2.3.
Optional parameters:
wait— Decide between synchronous and asynchronous processing.editable— Keep the resulting PDF fillable or flatten the form fields. See Editable PDFs.expires_in— Set a TTL for the generated PDF download link.field_overrides— Temporarily adjust field requirements or defaults.data_requests— Kick off a data collection or signature workflow before finalizing the PDF.
Processing Modes
Section titled “Processing Modes”Submissions sent to sync.api.docspring.com wait for processing and return the download_url in the response. Switching wait=false or using the asynchronous domain returns immediately with a pending submission. See Sync vs. Async Processing for flow diagrams, polling tips, and webhook guidance.
Editable PDFs
Section titled “Editable PDFs”By default, DocSpring “flattens” generated PDFs into static text, so the fields cannot be changed. You can instead generate PDFs that keep editable form fields (AcroForm fields). Only Text and Check fields become form fields; other display types are always static.
There are two ways to control this:
- Per submission: Set
editable: truein your submission request to make every field editable, oreditable: falseto flatten every field. An explicit value always takes precedence over the per-field option below. - Per field: Enable the “Editable” option on an individual field in the Template Editor. That field is rendered as an editable form field even when “Generate Editable PDFs” is off — as long as the submission does not set the
editableoption.
When the submission editable option is unset, each field falls back to the template’s “Generate Editable PDFs” setting or its own per-field “Editable” option.
Batch Generation
Section titled “Batch Generation”Need to create many PDFs at once? Use the batch endpoint to submit up to 50 requests together. Each entry can target a different template, switch between test/live, and specify its own metadata.