How to Use Content Placeholders in Templates

Problem

You need to dynamically assemble documents by inserting different content blocks (terms & conditions, pricing tables, signature blocks, product information) at creation time. Content placeholders in templates let you decide which content library items to include based on the data you're merging, and you can pre-fill fields, populate pricing tables, and assign recipients within each item.

Prerequisites

A PandaDoc API key or OAuth token
A PandaDoc template with at least one Content Placeholder (Smart Content) block
One or more content library items to insert

Solution

Step 1: Add a content placeholder to your template

In the PandaDoc editor, drag a Content Placeholder (Smart Content) block into the template where you want dynamic content to appear.

2822 — Template with Content Placeholder only

Step 2: Locate the required IDs

You need three IDs: the template ID, the block ID of each content placeholder, and the content library item IDs to insert.

Template ID -- the last segment of the template URL:

Block ID -- open the Content Placeholder settings in the template editor, or use the Template Details endpoint:

The Template Details response includes a content_placeholders array:

"content_placeholders": [
    {
        "uuid": "a3293bbf-9109-4478-a875-8271e10a99e9",
        "block_id": "Content Placeholder 1",
        "description": "Click here to add content library items"
    }
]

Content Library Item ID -- find it in the URL when viewing the item, just like the template ID:

2870 — Sample Pricing Table -> Content Library Item ID

Use the Content Library Item Details endpoint to inspect a library item's structure (fields, pricing, roles) and determine what values you can pre-fill.

Step 3: Build the request body

Include a content_placeholders array in your create document request. Each placeholder references its block_id and an array of content_library_items to insert. Within each item, you can optionally populate pricing tables, pre-fill fields, and assign recipients:

{
    "name": "API Sample Document for PandaDoc Template",
    "template_uuid": "{{template_id}}",
    "recipients": [
        {
            "email": "[email protected]",
            "first_name": "Jane",
            "last_name": "Roe"
        }
    ],
    "content_placeholders": [
        {
            "block_id": "{{block_id}}",
            "content_library_items": [
                {
                    "id": "{{cli_id}}",
                    "pricing_tables": [
                        {
                            "name": "Pricing Table 1",
                            "options": {
                                "currency": "USD",
                                "discount": {
                                    "is_global": true,
                                    "type": "absolute",
                                    "name": "Discount",
                                    "value": 2.26
                                }
                            },
                            "sections": [
                                {
                                    "title": "Sample Section",
                                    "default": true,
                                    "rows": [
                                        {
                                            "options": {
                                                "optional": true,
                                                "optional_selected": true,
                                                "qty_editable": true
                                            },
                                            "data": {
                                                "name": "Placeholder Panda",
                                                "price": 10,
                                                "qty": 3
                                            }
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "{{cli_id_2}}",
                    "recipients": [
                        {
                            "email": "[email protected]",
                            "first_name": "John",
                            "last_name": "Roe",
                            "role": "Signer"
                        }
                    ],
                    "fields": {
                        "Date": {
                            "value": "2019-12-31T00:00:00.000Z"
                        }
                    }
                }
            ]
        }
    ]
}

Step 4: Send the create request

POST /public/v1/documents

The response returns the document ID with status document.uploaded:

{
    "id": "YbyruETM8yzgMMaaLQa2RP",
    "name": "API Sample Document from PandaDoc Template",
    "status": "document.uploaded",
    "date_created": "2021-08-20T07:04:15.654510Z",
    "date_modified": "2021-08-20T07:04:15.654510Z",
    "uuid": "YbyruETM8yzgMMaaLQa2RP"
}

Wait for the document to reach document.draft status before proceeding. See Building a Reliable Document Creation Workflow for polling and webhook strategies.

Restrictions

Each content placeholder must be replaced with at least 1 content library item.
You can add up to 10 content library items per content placeholder.
A content library item must be unique within a single placeholder, but you can reuse the same item across different placeholders.

Verification

After creating the document, confirm it reaches document.draft status.
Open the document in the PandaDoc web app and verify the placeholder was replaced with the expected content library items:

2842 — Document with replaced content placeholder by content library items

Use the Document Details endpoint to inspect the created document programmatically.

How to Create a Document from a Template — template-based document creation
How to Work with Pricing Tables — configuring pricing table sections, taxes, and fees
How to Pre-Fill Document Fields — pre-filling field values at creation time
Content Library Item Details — inspect a library item's structure
Create Document API reference — full endpoint parameters