---
updatedAt: 2026-10-02T12:30:01.000Z
agentTools:
  projectIndex: https://developers.pandadoc.com/llms.txt
---

# How to Create a Document from a Template

Create a document from a PandaDoc template via API, with optional customization of fields, images, pricing, and content.

## Problem

You need to create a new document from a PandaDoc template via the API. Templates let you standardize document structure, branding, and content while dynamically filling in recipient details, field values, pricing, and images at creation time.

## Prerequisites

* A PandaDoc API key or OAuth token
* A PandaDoc template created in the web app ([help center guide](https://support.pandadoc.com/hc/en-us/articles/360041230753-Save-time-with-templates))
* The template's UUID (found in the browser address bar: `https://app.pandadoc.com/a/#/templates/{ID}/content`)

You can use the [sample PandaDoc template](https://app.pandadoc.com/get-this-template/?pt=public_template\&pub=eiC3a6qBVfEfbw7VCYgaeN) to test your first request.

## Solution

### Step 1: Build the request body

At minimum, provide the template UUID and recipients:

```json
{
  "name": "Contract for Acme Corp",
  "template_uuid": "ustHNnVaPCD6MzuoNBbZ8L",
  "recipients": [
    {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Roe",
      "role": "Signer"
    }
  ]
}
```

See the [Create Document API reference](https://developers.pandadoc.com/reference/create-document) for all available parameters.

### Step 2: Send the create request

```
POST /public/v1/documents
```

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

```json
{
  "id": "XHjv8z3SfDuTseFSnhprML",
  "name": "Contract for Acme Corp",
  "status": "document.uploaded",
  "date_created": "2021-07-05T15:05:27.787341Z",
  "date_modified": "2021-07-05T15:05:27.787341Z",
  "uuid": "XHjv8z3SfDuTseFSnhprML"
}
```

### Step 3: Wait for draft status

Document creation is asynchronous. The document is not ready until it reaches `document.draft` status. See [Building a Reliable Document Creation Workflow](https://developers.pandadoc.com/docs/reliable-document-workflow) for polling and webhook strategies.

> ❗️ Attempting to use a newly created document before it reaches `document.draft` status will result in a "404 document not found" response.

## Customization options

You can customize many aspects of the document at creation time. Each area has a dedicated guide:

| What                                                    | Guide                                                                                      |
| :------------------------------------------------------ | :----------------------------------------------------------------------------------------- |
| Pre-fill field values (text, date, checkbox, dropdown)  | [How to Pre-Fill Document Fields](https://developers.pandadoc.com/docs/prefill-fields)                                      |
| Add images to image blocks                              | [How to Add an Image to a Document via API](https://developers.pandadoc.com/docs/how-to-add-an-image-to-a-document-via-api) |
| Populate pricing tables with rows, taxes, and fees      | [How to Work with Pricing Tables](https://developers.pandadoc.com/docs/working-with-pricing-tables)                         |
| Populate text blocks with markdown content              | [How to Populate and Update Text Blocks](https://developers.pandadoc.com/docs/working-with-text-blocks)                     |
| Replace content placeholders with content library items | [How to Use Content Placeholders](https://developers.pandadoc.com/docs/create-with-content-placeholders-from-template)      |
| Set or override recipient signing order                 | [How to Set a Signing Order](https://developers.pandadoc.com/docs/set-signing-order)                                        |
| Create a document on a colleague's behalf               | [Create on Member's Behalf](https://developers.pandadoc.com/docs/create-document-on-members-behalf)                         |
| Use variables in the document name                      | [How to Use Variables in Document Titles](https://developers.pandadoc.com/docs/variables-in-document-titles)                |

## Verification

1. Check the document status — confirm it reaches `document.draft`.
2. Open the document in the PandaDoc web app to verify recipients, fields, and content rendered correctly.
3. Use the [Document Details](https://developers.pandadoc.com/reference/document-details) endpoint to inspect the created document programmatically.

## Troubleshooting

| Error                                          | Cause                                                                                                                                                                  |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP 403 `forbidden_error` on the status check | The account is over its Usage Credits limit and the document was not created. Stop polling. See [Usage Credits](https://support.pandadoc.com/en/?q=api+Usage+credits). |

## Related

* [Create Document API reference](https://developers.pandadoc.com/reference/create-document) — full endpoint parameters
* [Building a Reliable Document Creation Workflow](https://developers.pandadoc.com/docs/reliable-document-workflow) — async patterns and error handling
* [Create a Document from File Upload](https://developers.pandadoc.com/docs/create-document-from-file) — alternative creation method using uploaded files
* [Create a Document from Public PDF](https://developers.pandadoc.com/docs/create-and-send-a-document-from-a-publicly-available-pdf) — create from a publicly available URL