Create a Document from File

Upload a PDF, DocX, or an RTF to create a document.

Create from an upload or a URL

You have two options to create a document from file:

  1. Upload a local file. For this, use the multipart/form-data request type. Typically, the frameworks are handling the headers and you just need to pass a file to the request.
  2. Send a public URL in the document creation request like this:
curl --request POST '' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "My minimal document",
   "url": "",
   "recipients": [
       "email":"[email protected]",
       "role": "user"
   "parse_form_fields": false

See the Create from public PDF guide for more details.


Note: A file you upload is not stored in your PandaDoc account, so you have to upload it with every request.


We support PDF, DocX, and RTF. We've prepared two samples that you can use to test the request. Download them here:


  1. This method does not support multiple documents.
  2. The maximum supported file size is 50 MB. API returns "413 Request entity too large" in case of bigger files.
  3. PandaDoc does not support creating document from an encrypted PDF. To check whether a file is encrypted or not, try Get info -> Secure: Password Encrypted.

See all possible errors and the ways to mitigate them: Error handling.


Document creation is a non-blocking (asynchronous) operation

The document creation process may take time.

With a successful request, you receive a response with the created document's ID and status document.uploaded. After processing completes on our servers, usually a few seconds, the document moves to the document.draft status. Please wait for the webhook call or check this document's status before proceeding.

The change of status from document.uploaded to another status signifies the document is ready for further processing. Attempting to use a newly created document before PandaDoc servers process it will result in a "404 document not found" response.

PDF form fields

PandaDoc recognizes PDF form fields. To enable this feature, pass the optional parse_form_fields value as true when making a create document API call. We support Text fields, Dropdowns, and Signature fields.

If you would like to pass additional parameters to configure PDF form fields, use the PDF field name as an optId. You can use a PDF editor such as Adobe Acrobat, Foxit to get and edit field names in your PDF.

Download a Sample PDF with Form Fields

PDF/DocX/RTF field tags

This parsing format allows a word processor such as Microsoft Word or Google Docs to prepare a document and save it in PDF, DocX or RTF format.

Within the text, PandaDoc parses field tags. A field tag starts and ends with brackets. The field tag includes basic information on how to create a form field in the PandaDoc document. The request JSON object optId can also extend this information for even greater control.

Here is an example of how the field tag in a PDF/DocX/RTF is converted to a text field in the PandaDoc document:

Download a Sample PDF with Field Tags, including Radio Buttons

PDF field tag key


You can only use the ":" (colon) symbol between variables. This symbol cannot be trailing.

1fieldTypeField type from the table documented below.signature, or s for shorthand
2*Optional * denotes the field is not required.*
3roleRole name. Associate the field tag with a recipient role. Roles must be assigned to recipients in the request body. In this case we are using role s1 to keep the length short and denote the concept of "signer 1". s1 would be the value passed as role in a recipient JSON object.s1
4optIdOptional field Id. Specify more information about the field tag within the post request by using this id.sigBox17
5_____Use underscores to widen the field if desired. The form fields in PandaDoc will scale to the length and size of your field tag._____


Role names restrictions

Underscores are not supported in role names for a file with a Field Tag.

PDF/DocX/RTF field tag supported types

Field TypeShort NotationIs PandaDoc Field

Radio buttons limitations

  • Radio button options within the same block must be on the same page.
  • Preselection of options is not supported.
  • Different blocks require unique IDs.
  • Values for radio button options must be unique.
  • Each document can have a minimum of two and a maximum of 50 radio button options.


Fields in PandaDoc

The following article explains how to use Fields: Everything you need to know about Fields

"fields": {
    "textfield": {
        "value": "Jane",
        "role": "user"
    "dropdown": {
        "value": "opt1",
        "role": "user",
        "options": [
    "checkbox": {
        "value": true,
        "role": "user"
    "date": {
        "value": "2022-05-20",
        "role": "user"
    "initials": {
        "value": "",
        "role": "user"
    "signature": {
        "value": "",
        "role": "user"

Create on member's behalf

Create documents on your colleagues' behalf when it's needed. Simply add an additional owner section in the document creation request.
You can set an owner of a document as an email or membership_id. Unique member's identifier you may find in the List Members.

	"email":"[email protected]"


To set roles for a document from a PDF upload, you need to do these things:

  1. Associate the field tag in a document with a recipient role. For example, textfield:user___ denotes a required text field assigned to the role "user"
  2. Assign roles to recipients in the request body fields section:
"fields": {
    "textfield": {
        "value": "Jane",
        "role": "user"

Signing order

Set a signing order for documents created from a file.

"recipients": [  
    "email": "[email protected]",
    "first_name": "Josh",
    "last_name": "Ron",
    "role": "user",
    "signing_order": 1

Error handling

Error descriptionTypeRoot cause
PDF content hasn't been processed: document is broken or lockedProcessing errors: Failed to process document contentDocument converter service can’t process PDF. This may be caused by locked PDF or if it’s broken.
Error occurred while parsing PDF field tags. Please try PDF flattening or reach out to supportProcessing errors: Field tag / Form field validation errorDoc converter managed to parse PDF and extract tags, but at least 1 of them is invalid (having negative position, for example). Usually we recommend PDF flattening and it helps
No role='{role}' for field tag specified in recipients found, roles passed were {roles}Validation errors: Field tagsRole is invalid. When the role specified in field tag is empty or wasn’t provided in a payload for any recipient
All field tags within PDF must be declared within fields object of the JSON Payload. No field with optId='{optid}' found in fields object, fields passed were {optids}Validation errors: Field tagsLabel is invalid. Occurs when optId specified in field tag is empty or no field with name = optId was provided in a payload
One of field tags in PDF with type='{field}' doesn't have a roleValidation errors: Field tagsField tag in PDF has no role. One of field tags in PDF with type=% doesn't have a role.
Role for form field with name='{role}' is not provided in payloadValidation errors: Form fieldsRole for form field with ‘name’ is not provided. Occurs when role for form field with name=%s is not provided in payload
Field for form field with name='{name}' is not specified in payload, available names are {names}Validation errors: Form fieldsField ‘name’ is not specified in payload. Occurs when no field with name = form field name was provided in a payload
No role='{role}' for form field specified in 'recipients' found, roles passed were {roles}"Validation errors: Form fieldsFailed to resolve field actor for role in form field with ‘name’. Occurs when role from the form field is not found in recipient’s from payload
Failed to download file from link {url}.Source errorsError on attempt to download file.
An error has occurred on an attempt to download file using the provided ‘url’ in payload
Failed to download file from link {url} (status code: {status code})Source errorsError with HTTP status code on attempt to download file.
An error has occurred on an attempt to download file using the provided ‘url’ in payload - remote server responded with the HTTP status code
Content type='{type}' is not supported, available types are {types}Source errorsContent type is not supported.
Content type should be one of the following: PDF, ZIP, doc, docx, RTF
The maximum file size is exceeded, limit is {limit} MBSource errorsThe file size has exceeded the allowed limits. An error occurred while trying to download a file that is too large (limit is 50M).