Combine PDFs

Combine multiple PDFs from different sources into a single merged document.

Endpoint

POST /api/v2/combined_pdfs

Source Types

You can combine PDFs from various sources:

Submissions

Generated PDFs from template submissions:

{ "type": "submission", "id": "sub_1234567890abcdef01" }

The submission must already be processed and not expired. If you generate it with ?wait=false, wait until it has been processed before you combine it.

Combined PDFs

Previously combined PDFs:

{ "type": "combined_pdf", "id": "com_1234567890abcdef01" }

The combined PDF must already be processed and not expired.

Templates

Unfilled template PDFs:

{ "type": "template", "id": "tpl_1234567890abcdef01" }
{ "type": "template", "id": "tpl_1234567890abcdef01", "template_version": "1.2.3" }
{ "type": "template", "id": "tpl_1234567890abcdef01", "processed": false }

A template source merges the template’s processed PDF by default: the PDF that submissions are filled in on, decrypted and with its form fields removed. Set "processed": false to merge the PDF as it was uploaded.

Custom Files

Uploaded PDF files:

{ "type": "custom_file", "id": "cfi_1234567890abcdef01" }

Set delete_custom_files to true to delete these custom files once the merged PDF is ready. They’re kept if the merge fails, so you can retry. Other merges can’t use them after they’re deleted. This needs a live API token.

URLs

PDFs from external URLs, up to 500 MB each:

{ "type": "url", "url": "https://example.com/document.pdf" }

Example Request

{
  "source_pdfs": [
    { "type": "submission", "id": "sub_1234567890abcdef01" },
    { "type": "template", "id": "tpl_1234567890abcdef01" },
    { "type": "url", "url": "https://example.com/terms.pdf" }
  ],
  "metadata": {
    "document_type": "complete_package",
    "pdf_filename": "complete_contract_package"
  }
}

Key Features

Template Versions

For template sources, specify versions:

• "template_version": "draft" - Use draft version
• "template_version": "latest" - Use latest published version (default)
• "template_version": "1.2.3" - Use specific version

Custom Filename

Set a custom PDF filename via metadata:

{
  "metadata": {
    "pdf_filename": "merged_documents_2024"
  }
}

The combined PDF’s files.pdf.filename becomes merged_documents_2024.pdf. Without pdf_filename, it’s the combined PDF’s ID (com_1234567890abcdef01.pdf).

Filename rules:

• Max 128 characters
• Allowed: 0-9 A-Z a-z - _ .
• Other characters replaced with _

Expiration and Password

• expires_in: Number of seconds after processing until DocSpring deletes the merged PDF, its metadata and its password. A combined PDF that fails is kept for at least 48 hours, then expires.
• password: Encrypt the merged PDF with this password.

Credit Usage

Combining PDFs costs 4 credits for each source document, plus 4 credits for each unit of the combined PDF (one unit per 10 pages, for small files and light processing). Generating the source PDFs is charged separately. For example, combining two existing one-page PDFs costs 12 credits: 8 for the two source PDFs plus 4 for the 2-page combined PDF.

Combined PDFs have no test mode. Combining consumes credits even when you use a test API token or combine watermarked test PDFs. When your balance can’t cover it, the combined PDF is saved in the insufficient_credits state and the request returns a 402 with an insufficient_credits error and the combined_pdf_id.

Accounts on a plan purchased before prepaid credits were introduced can still combine PDFs without using credits.

How Credits WorkCredit calculations, examples, and what happens when your balance runs out

Use Cases

Multi-Page Forms

Combine multiple template submissions for complex forms:

{
  "source_pdfs": [
    { "type": "submission", "id": "sub_application_form" },
    { "type": "submission", "id": "sub_supporting_docs" },
    { "type": "template", "id": "tpl_terms_and_conditions" }
  ]
}

Document Packages

Create complete document packages with cover pages, forms, and attachments:

{
  "source_pdfs": [
    { "type": "template", "id": "tpl_cover_page" },
    { "type": "submission", "id": "sub_main_form" },
    { "type": "url", "url": "https://company.com/legal/terms.pdf" }
  ]
}

Addendum Pages

Handle form fields with truncated text by generating additional pages:

{
  "source_pdfs": [
    { "type": "submission", "id": "sub_main_form" },
    { "type": "submission", "id": "sub_addendum_page" }
  ]
}

API Reference: Combine PDFsView all parameters, example requests/responses, and code samples

Related Resources

Generate PDFsCreate PDFs from templates before combining them

Custom FilesUpload and manage custom PDF files for combining