--- updatedAt: 2026-10-02T14:12:55.000Z agentTools: projectIndex: https://developers.pandadoc.com/llms.txt --- # How to Create a Document from a File Upload Upload a PDF, DocX, or RTF to create a PandaDoc document via the API. ## 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`: ```json POST /public/v1/documents { "name": "My document", "url": "https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf", "recipients": [ { "email": "jane@example.com", "role": "user" } ], "parse_form_fields": false } ``` See the [Create Document API reference](https://developers.pandadoc.com/reference/create-document) 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](https://developers.pandadoc.com/docs/form-fields). * **Field tags** -- embed curly-brace-notation tags like `{textfield:s1:optId___}` directly in your PDF, DocX, or RTF source file. See [How to Add Field Tags to Documents](https://developers.pandadoc.com/docs/field-tags). ### Step 3: Assign roles to recipients When using field tags, associate each tag with a recipient role and map them in the `fields` section: ```json { "recipients": [ { "email": "jane@example.com", "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](https://developers.pandadoc.com/docs/reliable-document-workflow) for polling and webhook strategies. ## Sample files Test your integration with these sample files: **With native form fields:** * [Sample PDF with Form Fields](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf) **With field tags:** * [Sample PDF with Field Tags](https://5132871.fs1.hubspotusercontent-na1.net/hubfs/5132871/SamplePandaDocPdf_FieldTags%20\(2025\).pdf) * [Sample PDF with Stamp and Field Tags](https://5132871.fs1.hubspotusercontent-na1.net/hubfs/5132871/SamplePandaDocPdfWithStamp_FieldTags%20\(1\).pdf) ## 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. ## 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](https://developers.pandadoc.com/reference/document-details) endpoint to inspect fields, roles, and recipients programmatically. ## Troubleshooting ### Usage limit | 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). | ### Processing errors | Error | Cause | | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | | PDF content hasn't been processed: document is broken or locked | The PDF is corrupted or password-protected. Verify the file opens correctly and is not encrypted. | | Error occurred while parsing PDF field tags. Please try PDF flattening | At least one field tag has invalid positioning (e.g., negative coordinates). Flatten the PDF and retry. | ### Field tag validation errors | Error | Cause | | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------- | | No role='\{role}' for field tag specified in `recipients` found | The role in a field tag doesn't match any recipient role in the request. | | All field tags within PDF must be declared within `fields` object. No field with optId='\{optid}' found | A field tag's optId is missing from the `fields` object in the request body. | | One of field tags in PDF with type='\{field}' doesn't have a role | A field tag is missing its role segment (e.g., `{textfield_________}` instead of `{textfield:user_________}`). | ### Form field validation errors | Error | Cause | | :------------------------------------------------------------------- | :-------------------------------------------------------------- | | Role for form field with name='\{name}' is not provided in payload | A native form field's role is missing from the request. | | Field for form field with name='\{name}' is not specified in payload | A native form field name doesn't appear in the `fields` object. | | No role='\{role}' for form field specified in 'recipients' found | The role assigned to a form field doesn't match any recipient. | ### Source errors | Error | Cause | | :------------------------------------------------------ | :---------------------------------------------------------------------------------- | | Failed to download file from link \{url} | The URL is unreachable or returned an error. Verify the URL is publicly accessible. | | Content type='\{type}' is not supported | The file format is not PDF, DocX, or RTF. | | The maximum file size is exceeded, limit is \{limit} MB | The file exceeds the size limit. Reduce the file size or contact support. | ## Related * [Create Document API reference](https://developers.pandadoc.com/reference/create-document) -- full endpoint parameters * [How to Use Native PDF Form Fields](https://developers.pandadoc.com/docs/form-fields) -- configuring `parse_form_fields` * [How to Add Field Tags to Documents](https://developers.pandadoc.com/docs/field-tags) -- curly brace notation syntax and supported types * [Building a Reliable Document Creation Workflow](https://developers.pandadoc.com/docs/reliable-document-workflow) -- async patterns and error handling * [How to Set a Signing Order](https://developers.pandadoc.com/docs/set-signing-order) -- controlling recipient signing sequence * [Create on Member's Behalf](https://developers.pandadoc.com/docs/create-document-on-members-behalf) -- creating documents as another user * [How to Send a Document via API](https://developers.pandadoc.com/docs/send-document) -- sending the document after creation