DocSpring Rust SDK

The official Rust 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 · crates.io · 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 Rust 1.88 or later.

Add the crate to your Cargo.toml, with Tokio to run its async methods and serde_json to build the data you send:

[dependencies]
docspring = "4.3.0"
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Dates and times, such as the created_after filter, are chrono::DateTime values: add chrono = "0.4" if you pass one.

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

Create the client. Its methods are the docspring::Api trait's:

use docspring::Api;

let client = docspring::Client::from_env()?;

Or provide credentials directly:

let client = docspring::Client::builder()
    .token_id("API_TOKEN_ID")
    .token_secret("API_TOKEN_SECRET")
    .build()?;

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

let template_id = "tpl_1234567890abcdef01";
let body = docspring::models::CreateSubmissionRequest {
    data: Some(std::collections::HashMap::from([
        ("first_name".to_owned(), serde_json::json!("John")),
        ("last_name".to_owned(), serde_json::json!("Smith")),
        ("phone_number".to_owned(), serde_json::json!("+11234567890")),
    ])),
    metadata: Some(std::collections::HashMap::from([(
        "user_id".to_owned(),
        serde_json::json!(42),
    )])),
    test: Some(true),
    ..Default::default()
};

let result = client
    .create_submission(
        docspring::CreateSubmissionParams::builder()
            .template_id(template_id)
            .body(body)
            .build(),
    )
    .await;
match result {
    Ok(result) => println!("{result:#?}"),
    Err(error) => eprintln!("{error}"),
}

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.

The methods are the docspring::Api trait's, and they're async, so run them in a Tokio runtime. Each one takes its operation's parameters, built with a builder (CreateSubmissionParams::builder()), so an optional parameter added to the API later doesn't break your code. With the mockall feature, docspring::MockApi stands in for the client in your tests.

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

Methods return a Result whose error is a docspring::Error. For an error response it's Error::ResponseError, with the response's status, headers and body (content), and the decoded body in entity: the operation's error enum, whose variant is the status (CreateSubmissionError::Status422(ErrorResponse)).

The client checks each request against the API's request schemas before sending it. A request the API would reject fails with Error::RequestValidation(docspring::ValidationError) without being sent, whose details are models::ErrorDetails with a code, a message and a pointer into the body (or a parameter). Turn the check off with .validate_requests(false) on the ClientBuilder. The details are the ones the API's 422 response would have, so you get them without a round trip.

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 leaves out a response field added to the API after this release.
• 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.

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

• An enum value added to the API after this release comes back as the enum's Unknown variant, with the value as the API sent it, instead of failing the whole response. Enum types are #[non_exhaustive], as_str() gives the value, is_known() says whether this release knows it, and VALUES lists the ones it knows.
• An error response's variant comes from its status. Stock OpenAPI Generator decodes the first variant the body fits, so a 404 came back as Status422. ResponseContent keeps the response's headers, such as a 429's Retry-After.
• Date-time query parameters are sent in RFC 3339 format, and the multipart operations (upload_template, upload_template_document) compile.

On top of the generated code, we add:

• A client constructor that reads your credentials, region and host from the environment.
• docspring::Client::builder() and docspring::Client::from_env(), which build a client from an API token and a host or region, or from the environment variables.
• docspring::verify_webhook_signature(payload, signature_header, secret) checks a webhook request's X-DocSpring-Signature header (verify_webhook_signature_with_options takes a tolerance and now).

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.

MIT. See LICENSE.