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

Version 3.2.0. Requires Elixir ~> 1.18.

Install and configure

Add to your mix.exs dependencies:

def deps do
  [
    {:docspring, "~> 3.2.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"

submission = %{
  "data" => %{"first_name" => "John", "last_name" => "Smith", "phone_number" => "+11234567890"},
  "metadata" => %{"foo" => 123, "bar" => :baz}
}

result = api.generate_pdf(conn, template_id, submission)

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 its 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_fields_to_template	Add new fields to a Template
batch_generate_pdfs	Generate multiple PDFs
combine_pdfs	Merge submission PDFs, template PDFs, or custom files
copy_template	Copy a template
create_custom_file_from_upload	Create a new custom file from a cached S3 upload
create_data_request_event	Create a new event for emailing a signee a request for signature
create_data_request_token	Create a new data request token for form authentication
create_folder	Create a folder
create_html_template	Create a new HTML template
create_pdf_template	Create a new PDF template with a form POST file upload
create_pdf_template_from_upload	Create a new PDF template from a cached S3 file upload
create_webhook	Create a webhook
delete_folder	Delete a folder
delete_template	Delete a template
delete_webhook	Delete a webhook
expire_combined_submission	Expire a combined submission
expire_submission	Expire a PDF submission
generate_pdf	Generate a PDF
generate_preview	Generate a preview PDF for partially completed data requests
get_combined_submission	Check the status of a combined submission (merged PDFs)
get_data_request	Look up a submission data request
get_full_template	Fetch the full attributes for a PDF template
get_presign_url	Get a presigned S3 URL for direct file upload
get_submission	Check the status of a PDF
get_submission_batch	Check the status of a submission batch job
get_template	Check the status of an uploaded template
get_template_model_code	Generate typed model code for a template
get_template_schema	Fetch the JSON schema for a template
get_webhook	Get a webhook
list_combined_submissions	Get a list of all combined submissions
list_folders	Get a list of all folders
list_submissions	List all submissions
list_template_submissions	List all submissions for a given template
list_templates	Get a list of all templates
list_webhooks	Get a list of all webhooks
move_folder_to_folder	Move a folder
move_template_to_folder	Move Template to folder
publish_template_version	Publish a template version
rename_folder	Rename a folder
restore_template_version	Restore a template version
test_authentication	Test authentication
update_data_request	Update a submission data request
update_template	Update a Template
update_template_document	Update a template's document with a form POST file upload
update_template_document_from_upload	Update a template's document with a cached S3 file upload
update_webhook	Update a webhook

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.

API changes

DocSpring adds fields and enum values to API v1 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.
• An enum value added to the API after this release comes back as a string, so 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.16.0. The fork doesn't change the Elixir generator.

On top of the generated code, we add:

• A client constructor that reads your credentials, region and host from the environment.
• Fixes for multipart file uploads with Tesla 1.21 and later.

Because the code is generated, we can't merge pull requests that change it. Please open an issue or email support@docspring.com instead, and we'll fix it in the generator. AGENTS.md is a short guide for AI coding agents.

License

MIT. See LICENSE.