Generate a PDF

Create a new PDF by filling in a template with data.

HTTP Request

POST https://sync.api.docspring.com/api/v1/templates/<TEMPLATE_ID>/submissions

Authentication

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.

Parameters

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.)
  • version (string, optional): The version of the template to use (e.g. 1.2.3, 1.2, draft or latest). If not provided, the latest published version will be used (or the draft template, if no versions have been published). You can specify a partial version number to use the latest version that matches the prefix (e.g. 1.2 will use the latest version that starts with 1.2).
  • 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.)
  • expires_in (integer): The number of seconds before the submission will be expired after it is processed. Overrides the expiration settings on 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. Keys are "flattened" field names separated by the / character (e.g. person/first_name.) In other words, keys must match the names that you type into the "field name" input in the template editor. Values are an object containing the overrides for each field. These objects may include any properties found in the field schema. See below for some code examples that include the field_overrides option.

Asynchronous Response

The Generate PDF API endpoint is asynchronous, which means that we do not return a PDF immediately. Instead, we respond with a "pending" submission, and we process the PDF in the background. You must make a Get Submission API request to check the status of the submission. (If you use one of our API client libraries then this step will be handled for you automatically.)

download_url

When the Get Submission API request returns a processed submission, it will include a download_url property. This is a temporary URL that you can use to download the PDF file. This URL will expire after 24 hours.

We also return a permanent_download_url property, which is a URL that will never expire. However, this URL requires authentication with an API token (unless you have set Submission Privacy to Public in your Template Settings.)

Further Reading

Example Response

{
  "status": "success",
  "submission": {
    "batch_id": null,
    "data_requests": [
      {
        "id": "drq_1234567890abcdef01",
        "email": "[email protected]",
        "name": null,
        "order": 0,
        "sort_order": 0,
        "fields": null,
        "metadata": {},
        "state": "pending",
        "viewed_at": null,
        "completed_at": null,
        "data": null,
        "auth_type": "email_link",
        "auth_second_factor_type": "none",
        "auth_provider": null,
        "auth_session_started_at": null,
        "auth_session_id_hash": null,
        "auth_user_id_hash": null,
        "auth_username_hash": null,
        "auth_phone_number_hash": null,
        "ip_address": null,
        "user_agent": null
      }
    ],
    "editable": null,
    "expired": false,
    "expires_at": null,
    "id": "sub_1234567890abcdef01",
    "json_schema_errors": [],
    "metadata": {
      "foo": 123,
      "bar": "baz"
    },
    "password": null,
    "processed_at": null,
    "state": "waiting_for_data_requests",
    "template_id": "tpl_1234567890abcdef02",
    "template_type": "pdf",
    "template_version": null,
    "test": false,
    "truncated_text": {},
    "pdf_hash": null,
    "download_url": null,
    "permanent_download_url": null,
    "preview_download_url": null,
    "preview_generated_at": null,
    "audit_trail_download_url": null,
    "actions": []
  }
}

Example Code

import { PDFApi, Configuration } from 'docspring-ts'

const config = new Configuration({
  username: 'API_TOKEN_ID',
  password: 'API_TOKEN_SECRET',
})
const api = new PDFApi(config)

response = api.generatePDF({
  templateId: 'YOUR TEMPLATE ID',
  submission: {
    test: false,
    data: {
      first_name: 'John',
      last_name: 'Smith',
      favorite_color: 'Green',
    },
    metadata: {
      // Custom data to include in the request, for your own purposes
      example: 123,
    },
  },
})

console.log(response)

# 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",
      "passport": {
        "number": "123456789",
        "country": "USA"
      }
    },
    "metadata": {                     # Custom data to include in the request, for your own purposes
      "user_id": 123,
    },
    'field_overrides': {
      'first_name': {
        'required': False
      },
      'passport/number': {
        'required': False
      }
    }
  }
)

print("Download your PDF at: %s" % submission.download_url)

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_1234567890abcdef01";
          var createSubmissionData = new CreateSubmissionData(
            false,  // true to generate a test PDF (watermarked)
            new {
              first_name = 'John',
              last_name = 'Smith',
              phone_number = "+11234567890"
            },
            fieldOverrides: new {
              phone_number = new {
                required = false
              }
            }
          );
          var response = apiInstance.GeneratePDF(templateId, createSubmissionData);
          Debug.WriteLine(response);

          // 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 "https://sync.api.docspring.com/api/v1/templates/$TEMPLATE_ID/submissions" \
    -u "$API_TOKEN_ID:$API_TOKEN_SECRET" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"data":{"first_name": "John", "last_name": "Smith", "phone_number": "+11234567890"}, "metadata": { "user_id": 123 }, "field_overrides": { "first_name": { "required": false }}}'
}

get_submission() {
  curl -s "https://sync.api.docspring.com/api/v1/submissions/$1" \
    -u "$API_TOKEN_ID:$API_TOKEN_SECRET"
}

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

RESPONSE=$(generate_pdf)
echo $RESPONSE
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)
done

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

results matching ""

    No results matching ""