How to Create a Document from a File Upload

Problem

You need to create a PandaDoc document from a PDF, DocX, or RTF file. You can either upload a local file or provide a publicly accessible URL.

Prerequisites

• A PandaDoc API key or OAuth token
• A PDF, DocX, or RTF file (local or publicly accessible URL)
• Recipients to assign to the document

Solution

Step 1: Choose your upload method

Option A -- Upload a local file using multipart/form-data:

Use your HTTP framework's file upload support to send the file. Most frameworks handle the Content-Type: multipart/form-data header automatically when you attach a file.

Option B -- Provide a public URL using application/json:

POST /public/v1/documents

{
  "name": "My document",
  "url": "https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf",
  "recipients": [
    {
      "email": "[email protected]",
      "role": "user"
    }
  ],
  "parse_form_fields": false
}

See the Create Document API reference for full parameters.

🚧

A file you upload is not stored in your PandaDoc account. You must upload it with every request.

Step 2: Add interactive fields (optional)

Choose one of two approaches to add interactive fields to uploaded files:

• Native PDF form fields -- set parse_form_fields: true to have PandaDoc recognize form fields already embedded in the PDF. See How to Use Native PDF Form Fields.
• Field tags -- embed bracket-notation tags like [textfield:s1:optId___] directly in your PDF, DocX, or RTF source file. See How to Add Field Tags to Documents.

Step 3: Assign roles to recipients

When using field tags, associate each tag with a recipient role and map them in the fields section:

{
  "recipients": [
    {
      "email": "[email protected]",
      "role": "user"
    }
  ],
  "fields": {
    "textfield": {
      "value": "Jane",
      "role": "user"
    }
  }
}

The role in the field tag (e.g., [textfield:user___]) must match a role assigned to a recipient.

Step 4: 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 for polling and webhook strategies.

Sample files

Test your integration with these sample files:

With native form fields:

• Sample PDF with Form Fields

With field tags:

• Sample PDF with Field Tags
• Sample PDF with Stamp and Field Tags

Limitations

• Only one file per request (multiple documents not supported).
• Maximum file size: 100 MB (returns 413 Request Entity Too Large if exceeded).
• Encrypted PDFs are not supported. To check: open the PDF properties and look for "Secure: Password Encrypted."
• Supported formats: PDF, DocX, RTF.

Troubleshooting

Processing errors

Field tag validation errors

Form field validation errors

Source errors

Verification

1. Check the document status -- confirm it reaches document.draft.
2. Open the document in the PandaDoc web app to verify the file rendered correctly and fields are recognized.
3. Use the Document Details endpoint to inspect fields, roles, and recipients programmatically.

Related

• Create Document API reference -- full endpoint parameters
• How to Use Native PDF Form Fields -- configuring parse_form_fields
• How to Add Field Tags to Documents -- bracket notation syntax and supported types
• Building a Reliable Document Creation Workflow -- async patterns and error handling
• How to Set a Signing Order -- controlling recipient signing sequence
• Create on Member's Behalf -- creating documents as another user
• How to Send a Document via API -- sending the document after creation