DocSpring Python SDK

The official Python client for the DocSpring API. DocSpring fills PDF forms with your data, generates PDFs and Word documents from HTML and Word templates, combines PDFs and collects e-signatures.

Documentation · API reference · PyPI · Changelog

The code in this repository is generated from DocSpring's OpenAPI spec (About this SDK). Issues and pull requests are welcome.

Version 4.3.0. Requires Python >=3.10.

Install and configure

Install the package:

pip install --upgrade docspring

Configure authentication via environment variables:

export DOCSPRING_TOKEN_ID="API_TOKEN_ID"
export DOCSPRING_TOKEN_SECRET="API_TOKEN_SECRET"

You can also configure the region or host. The host takes priority over the region:

export DOCSPRING_REGION="US" # US or EU (defaults to US)
export DOCSPRING_HOST="docspring.yourcompany.com" # For on-premise deployments

Import and initialize the DocSpring client:

from docspring import Client
client = Client()

Or provide credentials directly:

from docspring import Client
client = Client(api_token_id='API_TOKEN_ID', api_token_secret='API_TOKEN_SECRET')

Generate a PDF

Fill a template with data (use your template's ID in place of tpl_1234567890abcdef01):

template_id = "tpl_1234567890abcdef01"
body = {
    "data": {
        "first_name": "John",
        "last_name": "Smith",
        "phone_number": "+11234567890",
    },
    "metadata": {"user_id": 42},
    "test": True,
}

response = client.create_submission(template_id, body)
print(response)

By default the call waits for the PDF, for up to 95 seconds, and the submission in the response has a link to download it (files.pdf.download_url). Set wait to false to get a pending submission straight away. Sync vs. async processing covers the time limit, status checks and webhooks.

Methods

docs/Client.md has each method's parameters and return type, and docs/ has the models. The API reference has Python code for every method.

Errors

Methods raise docspring.ApiException for an error response (or a subclass from docspring.exceptions, such as NotFoundException), with the HTTP status in status and the body in body.

The client checks each request against the API's request schemas before sending it. A request the API would reject raises docspring.RequestValidationError (a ValueError), whose details are dicts with code, message and a pointer into the body (or a parameter). Turn the check off with client.api_client.configuration.client_side_validation = False. The details are the ones the API's 422 response would have, so you get them without a round trip.

API changes

DocSpring adds fields and enum values to API v2 without releasing a new API version. Changes that would break existing code, such as removing or renaming a field, go in a new API version (API changes). So this SDK keeps working with responses that are newer than it is:

• The model keeps a response field added to the API after this release in its additional_properties dict. The objects defined inside a model, such as a template's document, leave it out.
• An enum value added to the API after this release comes back as the API sent it: handle values you don't recognize.

Upgrade the SDK to read new fields and enum values. The changelog lists what each release adds.

About this SDK

This SDK is generated from DocSpring's OpenAPI spec with DocSpring's fork of OpenAPI Generator 7.26.0. The fork changes the Python generator:

• An enum value added to the API after this release becomes a member of its own, which compares and serializes as the value, instead of raising ValueError. Iterating an enum type gives the values this release knows.
• A union (CombinedPdfSourceInput) takes a dict or one of its models, picked by the dict's type or operator. Stock OpenAPI Generator ignores a dict's keys and sends null.

On top of the generated code, we add:

• A client constructor that reads your credentials, region and host from the environment.
• docspring.verify_webhook_signature(payload, signature_header, secret) checks a webhook request's X-DocSpring-Signature header, with tolerance and now keyword arguments.

Each release regenerates every file, so a change made only here would be lost in the next one. Issues and pull requests are welcome all the same: open an issue or a pull request, or email support@docspring.com, and we'll make the fix in the generator so that every release keeps it. AGENTS.md is a guide for AI coding agents that integrate this SDK.

License

MIT. See LICENSE.