Generate a PDF

Create a new PDF job submission.

HTTP Request



You must send an Authorization header with the value Basic followed by base 64 encoded token_id:token_secret.

For example: Authorization: Basic dG9rZW5faWQ6dG9rZW5fc2VjcmV0Cg==

See the Authentication documentation for more information.


The request body must be a JSON object with the following keys:

  • data (object): Data to fill in the fields. Must match the template schema.
  • metadata (object, optional): Any additional data, such as a user id.
    • metadata will be included in webhook requests.
    • You can set pdf_filename in the metadata to customize the PDF filename in the download URL (see below.)
  • test (boolean): true to generate a test PDF, false for a live PDF. Test PDFs are free, but watermarked. Note: A test API key can only be used to generate test PDFs.
  • editable (boolean, optional): true to generate an editable PDF with fillable form fields. false to generate a static PDF with fixed text. (Note: When no value is provided, we use the default setting from the template.)
  • data_requests (array, optional): Request information or signatures from one or more people. (See the Create Data Request documentation for more info and examples.)
  • field_overrides (object, optional): Overrides field settings, such as required. The object for each field must match the field schema. See below for a code example that includes field_overrides.

Customize the PDF Filename in the Download URL

You can customize the PDF filename by setting the pdf_filename key in the metadata. (DocSpring will add the .pdf extension automatically.)

For example, if you set pdf_filename to custom_pdf_file123, the PDF URL will end with: /submissions/<submission_id>/custom_pdf_file123.pdf

(By default, the PDF URL will end with /submissions/<submission_id>.pdf)

Custom PDF filenames have a maximum length of 128 characters, and can include the following characters: 0-9 A-Z a-z - _ .. Any other characters will be replaced with an underscore.


If the full text can't fit in a field and the field's "Overflow" option is set to "Truncate", we will store any truncated text in the submission. This will be returned as a truncated_text object when you make a Get Submission API request:

  "submission": {
    "truncated_text": {
      "title": ["text that could not fit in the field"]

Every key in the truncated_text object is a field name, and each value is an array of strings. Most of the time this will be an array with a single string. However, a template can contain multiple fields that share the same name. If your template has multiple fields that share the same name, then the array may contain multiple truncated strings for each individual field.

If you will be relying on the returned truncated_text, then it would be a good idea to give all of your fields a unique name and send duplicate data for each field.

Use-case: Some government and immigration forms have an optional addendum page that can be attached if any text is too long to fit in one of the fields. You could check the truncated_text for each submission, and set up another template to generate any addendum pages when necessary. You can then use the Combine PDFs API endpoint to merge the main PDF form and any addendum pages.

Example Response

  "status": "success",
  "submission": {
    "id": "sub_000000000000000001",
    "template_id": "tpl_000000000000000001",
    "batch_id": null,
    "state": "pending",
    "test": false,
    "editable": null,
    "expired": false,
    "expires_at": null,
    "json_schema_errors": [],
    "truncated_text": {},
    "metadata": {
      "foo": 123,
      "bar": "baz"
    "processed_at": null,
    "data_requests": [],
    "pdf_hash": null,
    "download_url": null,
    "permanent_download_url": null,
    "actions": []

Example Code

// Find your API tokens here:

import DocSpring from 'docspring'

var config = new DocSpring.Configuration()
config.apiTokenId = 'DOCSPRING_API_TOKEN_ID'
config.apiTokenSecret = 'DOCSPRING_API_TOKEN_SECRET'
docspring = new DocSpring.Client(config)

var template_id = 'tpl_000000000000000001'
var submission_data = {
  editable: false,
  data: {
    title: 'Test PDF',
    description: 'This PDF is great!',
  metadata: {
    user_id: 123,
  field_overrides: {
    title: {
      required: false,
  wait: true,
docspring.generatePDF(template_id, submission_data, function (
) {
  if (error) {
    console.log(response, error)
    throw error
  var submission = response.submission
  console.log('Download your PDF at:', submission.download_url)
# Find your API tokens here:

require 'docspring'


DocSpring.configure do |c|
  c.api_token_id = 'api_token123'
  c.api_token_secret = 'testsecret123'

client =
template_id = 'tpl_000000000000000001'

response = client.generate_pdf(
  template_id: template_id,
  data: {
    title: 'Test PDF',
    description: 'This PDF is great!',
  field_overrides: {
    title: {
      required: false
submission = response.submission

puts "Download your PDF at: #{submission.download_url}"
# This is a live example that you can run in the Python interpreter
import docspring

client = docspring.Client()
client.api_client.configuration.username = "yRaaR9JmTPtGX7EN"
client.api_client.configuration.password = "IB3TRkSdm4f2BdtU_D3YgxjdMB7l-r2fOgvxD1Yzwec"

submission = client.generate_pdf(
  "6zz3dYRYM67fxMXA",  # ID of a template that you have configured
    "test": True,                       # test documents are free but watermarked
    "data": {                           # Data to render in the template
      "first_name": "John",
      "last_name": "Smith",
      "favorite_color": "Green",
    "metadata": {                     # Custom data to include in the request, for your own purposes
      "user_id": 123,
    'field_overrides': {
      'first_name': {
        'required': False

print("Download your PDF at: %s" % submission.download_url)
// You can run this example in the PHP interactive shell (php -a)
// Find your API tokens here:

$docspring = new \DocSpring\Client();

$template_id = 'tpl_000000000000000001'; // string |
$submission_data = new \DocSpring\Model\SubmissionData();
  "title" => 'Test PDF',
  "description" => 'This is a test PDF!',
  "title" => [
    "required" => false
$submission = $docspring->generatePDF($template_id, $submission_data);

echo "Download your PDF at: " . $submission->getDownloadUrl();
using System;
using System.Diagnostics;
using DocSpring.Client.Api;
using DocSpring.Client.Client;
using DocSpring.Client.Model;

namespace Example
    public class DocSpringExample
        public void main()
          Configuration.Default.Username = "yRaaR9JmTPtGX7EN";
          Configuration.Default.Password = "IB3TRkSdm4f2BdtU_D3YgxjdMB7l-r2fOgvxD1Yzwec";

          var apiInstance = new PDFApi();
          string templateId = "tpl_000000000000000001";
          var createSubmissionData = new CreateSubmissionData(
            false,  // true to generate a test PDF (watermarked)
            new {
              title = "Test PDF",
              description = "This PDF is great!"
            fieldOverrides: new {
              title = new {
                required = false
          var response = apiInstance.GeneratePDF(templateId, createSubmissionData);

          // The PDF will now be in the "pending" state until it is processed.
          // You may want to call GetSubmission once per second until
          // the state changes to "processed".
          // Alternatively, you can set up a webhook notification.

The following example waits for the PDF to be processed, then prints the download URL.

# This is a live example that you can run in your console.

export API_TOKEN_ID="yRaaR9JmTPtGX7EN"
export API_TOKEN_SECRET="IB3TRkSdm4f2BdtU_D3YgxjdMB7l-r2fOgvxD1Yzwec"
export TEMPLATE_ID="6zz3dYRYM67fxMXA"

generate_pdf() {
  curl -s "$TEMPLATE_ID/submissions" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"data":{"first_name": "John", "last_name": "Smith", "favorite_color": "Blue"}, "metadata": { "user_id": 123 }, "field_overrides": { "first_name": { "required": false }}}'

get_submission() {
  curl -s "$1" \

get_json_value() {
  echo "$1" | sed -n 's/.*"'"$2"'":"\([^"]\+\)".*/\1/p'

SUBMISSION_ID=$(get_json_value "$RESPONSE" id)
SUBMISSION_STATE=$(get_json_value "$RESPONSE" state)

echo "Waiting for PDF to be processed..."
while [[ "$SUBMISSION_STATE" = "pending" ]]; do
  sleep 1
  RESPONSE=$(get_submission "$SUBMISSION_ID")
  SUBMISSION_STATE=$(get_json_value "$RESPONSE" state)

echo "Download your PDF at:"
get_json_value "$RESPONSE" download_url

results matching ""

    No results matching ""