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.)
  • 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. The object for each field must match the field schema. See below for a code example that includes field_overrides.

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.)


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": {
    "id": "sub_000000000000000001",
    "template_id": "tpl_000000000000000001",
    "batch_id": null,
    "state": "pending",
    "test": false,
    "editable": null,
    "expired": false,
    "expires_at": null,
    "password": 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,
    "preview_download_url": null,
    "preview_generated_at": 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: {
    first_name: 'John',
    last_name: 'Smith',
    phone_number: "+11234567890"
  metadata: {
    user_id: 123,
  field_overrides: {
    phone_number: {
      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: {
    first_name: 'John',
    last_name: 'Smith',
    phone_number: "+11234567890"
  field_overrides: {
    phone_number: {
      required: true
submission = response.submission

puts "Download your PDF at: #{submission.download_url}"
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,

# 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();
  "first_name" => 'John',
  "last_name" => 'Smith',
  "phone_number" => '+11234567890',
  "phone_number" => [
    "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 {
              first_name = 'John',
              last_name = 'Smith',
              phone_number = "+11234567890"
            fieldOverrides: new {
              phone_number = 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", "phone_number": "+11234567890"}, "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 ""