DocSpring Elixir SDK

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

Documentation · API reference · Hex · Changelog

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

Version 4.1.0. Requires Elixir ~> 1.18.

Install and configure

Add to your mix.exs dependencies:

def deps do
  [
    {:docspring, "~> 4.1.0"}
  ]
end

Then run:

mix deps.get

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

Initialize the client connection and module:

conn = Docspring.Connection.new()
api = Docspring.Api.Client

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
}

result = api.create_submission(conn, template_id, body)

case result do
  {:ok, data} ->
    IO.inspect(data)

  {:error, reason} ->
    IO.inspect(reason)
end

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

HexDocs has each method's parameters and return type, and HexDocs has the models. The API reference has Elixir code for every method.

Method	Description
add_template_fields	Add fields to a template
copy_template	Copy a template
create_combined_pdf	Combine PDFs
create_custom_file_from_upload	Create a custom file from an upload
create_folder	Create a folder
create_signature_request_event	Record a signature request event
create_signature_request_token	Create a signature request token
create_submission	Generate a PDF
create_submission_batch	Generate PDFs in a batch
create_template	Create a template
create_webhook	Create a webhook
delete_custom_file	Delete a custom file
delete_folder	Delete a folder
delete_template	Delete a template
delete_webhook	Delete a webhook
expire_combined_pdf	Expire a combined PDF
expire_submission	Expire a submission
generate_submission_files	Generate more files
generate_submission_preview	Generate a preview PDF
get_combined_pdf	Get a combined PDF
get_custom_file	Get a custom file
get_folder	Get a folder
get_presign_url	Get a presigned URL to upload a file
get_signature_request	Get a signature request
get_submission	Get a submission
get_submission_batch	Get a batch
get_template	Get a template
get_template_diff	Compare a version of a template with the one before it
get_template_model_code	Generate typed code for a template's submission data
get_template_page_images	Get images of a template's pages
get_template_schema	Get the JSON Schema of a template's submission data
get_webhook	Get a webhook
list_combined_pdfs	List combined PDFs
list_custom_files	List custom files
list_folders	List folders
list_submissions	List submissions
list_template_fields	List a template's fields
list_template_submissions	List a template's submissions
list_templates	List templates
list_webhooks	List webhooks
move_folder	Move a folder
move_template	Move a template to a folder
publish_template_version	Publish a template version
remove_template_fields	Remove fields from a template
rename_folder	Rename a folder
reorder_template_fields	Reorder a template's fields
restore_template_version	Restore a template version
test_authentication	Test authentication
update_signature_request	Update a signature request
update_template	Update a template
update_template_document	Replace a template's PDF
update_template_fields	Update a template's fields
update_webhook	Update a webhook
upload_template	Create a PDF template from an uploaded PDF
upload_template_document	Replace a template's PDF with an uploaded PDF
validate_submission	Check a submission without creating it

Errors

Functions return {:ok, model} for each documented response, including error responses (for example {:ok, %Docspring.Model.ErrorResponse{}}), and {:error, reason} for anything else: a %Tesla.Env{} for a status the API doesn't document, or the error from the HTTP adapter or the JSON decoder.

The client checks each request against the API's request schemas before sending it. A request the API would reject returns {:error, %Docspring.ValidationError{}} without being sent, whose details are Docspring.Model.ErrorDetail structs with a code, a message and a pointer into the body (or a parameter). Turn the check off with Docspring.Connection.new(validate_requests: 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 struct leaves out a response field added to the API after this release.
• Enum values in responses are strings, so a value added to the API after this release comes back as it is: 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 Elixir generator:

• Enum modules type their values as strings and list the values this release knows (values/0). An enum value added to the API after this release comes back as the API sent it.

On top of the generated code, we add:

• A client constructor that reads your credentials, region and host from the environment.

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.