This plugin connects your app to DocSpring's API (version 2). Sign up for a free trial at: https://docspring.com
1. Create an API token in DocSpring: https://app.docspring.com/api_tokens
2. Set your API Token ID and Secret in the DocSpring plugin settings.
3. If your DocSpring account is in the EU region, set the "Region" field to "EU" in the plugin settings. Otherwise, leave this field blank. (It will use the US servers by default.) If you run DocSpring on your own servers, set it to your server's URL, such as https://docspring.example.com. (The AU region has closed.)
4. Create a template in DocSpring.
5. Use the "DocSpring - Create PDF Submission" action in Workflows > Plugins to generate a PDF.
6. The "PDF File" property will be available as a "Result of Step X" property. This is the download URL of the file.

"PDF File" is a *temporary* URL. Please make sure that you use Bubble's ":saved to S3" option so that Bubble will download the PDF and store it (see our demo app for an example). If you don't use "PDF File:saved to S3", then you won't be able to access your PDF after the link expires.

- You can change the name of the PDF file by setting the "pdf_filename" key under the Metadata option. (You don't need to include .pdf at the end.)


Sending Data
------------------------------------

DocSpring checks your Data against the template's fields, and Bubble sends every value as text:

- Date fields take dates as YYYY-MM-DD, such as 2026-10-27. To send a Bubble date, use ":formatted as" with a custom format that gives year-month-day.
- Email fields take an email address (or nothing).
- Number fields don't take text: set their type to "text" in your template.
- Check box fields take true or false: turn on "Enable Booleans" to send "true" and "false" as booleans.
- Use "/" in a key for nested fields and lists, such as "address/city" or "items/0/name".
- To send keys that aren't fields of the template, enable "Allow Additional Properties in JSON Data" in your template's Settings.
- An empty Data list is checked too: fill in the template's required fields.


Sending Images
------------------------------------

If your PDF template has an image field, you can send an image as a URL or a base64-encoded string. You will need to append "/url" or "/base64" to the image field's name when you are setting up your Create PDF Submission call.

For example, if you have an image field named "image" and you want to use an image from a URL, you can use "image/url" as the key for your Data, and enter a URL (or a Bubble image) in the value field.


Actions
------------------------------------

- Create PDF Submission, Get PDF Submission: generate a PDF, and get it again later.
- Generate PDFs in a Batch, Get Submission Batch: up to 50 PDFs in one request.
- Check Data: check data against a template without generating anything.
- Find Submissions, Generate Submission Files (page images), Expire Submission.
- Combine PDFs, Get Combined PDF.
- Create Signature Request, Create Signing Link, Get Signature Request: ask people to fill in and sign a PDF.
- Find Templates, Get Template, Create Template, Replace Template PDF, Copy Template, Move Template, Publish Template Version, List / Add / Update / Remove Template Fields, Get Template Page Images.
- List Folders, Create Folder.
- Create Webhook, Delete Webhook: DocSpring calls one of your app's backend workflows when something happens, such as a PDF being ready (submission.processed) or a signature request being completed (signature_request.completed). Make the backend workflow public, use its URL, and detect its data from a test event.
- Make an API Call: any other request to the DocSpring API.

Actions that generate files wait up to 45 seconds. If the PDF isn't ready by then, the action returns its ID: get the PDF later with Get PDF Submission, or create a webhook for the submission.processed event.

Every action returns "Success", "Error Message" and "Response JSON" (the API's response). API reference: https://docspring.com/docs/api/


Upgrading from Version 1
------------------------------------

Version 2 uses DocSpring's API v2. Your workflows keep working, with these changes:

- Date fields need YYYY-MM-DD dates, and email fields need email addresses (see Sending Data).
- Get PDF Submission's hash is the PDF's SHA-256 hash (it was MD5), and its "Password" is always empty.
- Get PDF Submission's "Error Message" has the submission's error message when its PDF couldn't be generated ("Success" is still yes: check "Submission State").
- A submission waiting for its signature requests is in the waiting_for_signature_requests state (it was waiting_for_data_requests).
- "Response JSON" has API v2's format.
- If you run DocSpring on your own servers, upgrade them to a release with API v2 first, or keep version 1.7.0 of this plugin.


Plugin Settings (Dev vs Deployed)
------------------------------------------------
When configuring the DocSpring plugin in your app, you will see "Token ID", "Token Secret", and "Region" fields. There are also the same three fields with a "- dev." suffix. The "dev" fields are a Bubble feature that allow you to use different settings while developing/testing your app vs. the live deployed version.

These "dev" fields are not related to DocSpring's concept of test/live PDFs, but typically you would set a test API token in the "dev" fields and a live API token in the non-dev fields.


Feedback
------------------------------------

Please let us know about any bugs and issues at: bubble@docspring.com