DocSpring Integration Guide

Quick Start

1. Install the official client library:

   Node.js

   npm install docspring

   Python

   pip install docspring

   Ruby

   gem install docspring

   PHP

   composer require docspring/docspring-php

   Java

2. Basic PDF generation (Python example):

   import docspring import urllib.request

   client = docspring.Client() client.api_client.configuration.username = "YOUR_API_TOKEN_ID" client.api_client.configuration.password = "YOUR_API_TOKEN_SECRET"

   response = client.generate_pdf({ "template_id": "tpl_xxx", "test": True, "data": { "first_name": "John", "last_name": "Smith" } })

   urllib.request.urlretrieve(response.submission.download_url, "output.pdf")

Core Concepts

1. Templates

   • Manage at https://app.docspring.com
   • Each template has a unique ID (e.g. tpl_xxx)
   • Define field names, types, and validation
   • Get the template_id from the URL or the “API” tab

2. Authentication

   • Generate tokens at https://app.docspring.com/api_tokens
   • Test tokens (test_xxx) produce watermarked PDFs
   • Live tokens (live_xxx) produce production PDFs
   • Use HTTP Basic auth with token_id:token_secret
   • Don’t commit tokens to source control

3. PDF Generation

   • Synchronous (recommended): sync.api.docspring.com returns the finished PDF immediately.
   • Can use sync subdomain for all API requests.
   • Append "?wait=false" to the URL to return a pending submission immediately.
   • Asynchronous: api.docspring.com returns a submission ID, then you poll for completion
   • For EU region: sync.api-eu.docspring.com or api-eu.docspring.com

Advanced Features

1. Batch Processing

   response = client.batch_generate_pdfs({ "template_id": "tpl_xxx", "submissions": [ {"data": {"name": "John"}}, {"data": {"name": "Jane"}} ] })

   Up to 50 PDFs per request

2. Data Requests (e.g., for signatures)

   response = client.generate_pdf({ "template_id": "tpl_xxx", "data": {"company": "Acme Inc"}, "data_requests": [{ "email": "john@example.com", "fields": ["signature", "date"], "auth_type": "email_link" }] })

   submission.state will be "waiting_for_data_requests"

3. Combine PDFs

   response = client.combine_pdfs({ "source_pdfs": [ {"type": "submission", "id": "sub_xxx"}, {"type": "submission", "id": "sub_yyy"} ] })

4. Field Customization

   response = client.generate_pdf({ "template_id": "tpl_xxx", "data": {"name": "John"}, "field_overrides": { "signature": { "required": True, "alignment": "center", "font_size": 10 } } })

Common Issues & Solutions

1. PDF Generation

   • Use the sync API for simpler flow (no polling or webhooks needed)
   • Check submission.state == "processed" (if not using sync API)
   • Handle submission.json_schema_errors for invalid data
   • download_url expires after 24 hours; use permanent_download_url for long-term access
   • Check for truncated_text in logs when text overflows
   • Batch requests support up to 50 PDFs

2. Data Formatting

   • Field names are case-sensitive
   • Can use %%LF%% if \n doesn’t work for new lines
   • Send dates as YYYY-MM-DD (ISO8601)
   • Use numeric types for numbers, boolean true/false for booleans

3. Templates

   • All templates have a JSON schema based on the fields defined in the template editor
   • Submission data is validated against the JSON schema before PDF generation
   • Test changes with test tokens
   • Validation happens on submission
   • Existing submissions aren’t affected by edits

API Response Examples

1. Successful submission

   { "status": "success", "submission": { "id": "sub_xxx", "state": "processed", "download_url": "https://...", "permanent_download_url": "https://..." } }

2. Validation error

   { "status": "error", "error": "validation_error", "json_schema_errors": [ { "field": "name", "message": "is required" } ] }

More details: https://docspring.com/docs/