# Create Document from File Upload

## Create from an upload
> See the [Create from PDF](https://developers.pandadoc.com/docs/create-document-from-file) tutorial for the usage specifics and sample PDF files.

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


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "PandaDoc Public API",
    "description": "PandaDoc API spans a broad range of functionality to help you build incredible documents automation experiences inside your product.\n\nPandaDoc API is organized around REST. Our API has predictable resource-oriented URLs and uses standard HTTP response codes, authentication, and verbs.\n\n## Getting started\n\nYou can start testing PandaDoc API with a sandbox key on our [Enterprise](https://www.pandadoc.com/pricing/) plan, either active or in trial.\n\nGenerate your [sandbox key](https://developers.pandadoc.com/reference/sandbox-key) on the Developer Dashboard with predefined [rate limits](https://developers.pandadoc.com/reference/limits). Or contact our solutions expert if you work with high-transaction volumes.\n\n## Guides\n\nIf you’re just getting started with PandaDoc, you may want to jump straight into one of our [getting started guides](https://developers.pandadoc.com/docs/getting-started) for the feature you’re most interested in, whether that’s:\n\n- [Create from template](https://developers.pandadoc.com/docs/create-send-document),\n- [Upload and send a local PDF](https://developers.pandadoc.com/docs/upload-and-send-a-local-pdf),\n- or [Listening for changes in document status](https://developers.pandadoc.com/docs/listen-document-status-changes).\n\nWe also recommend you to discover our dynamic content generation on a fly: [Create from a template with content placeholder](https://developers.pandadoc.com/docs/create-with-content-placeholders-from-template).\n",
    "termsOfService": "https://www.pandadoc.com/master-services-agreement/",
    "contact": {
      "name": "PandaDoc API Support",
      "url": "https://developers.pandadoc.com/",
      "email": "api-track@pandadoc.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/PandaDoc/pandadoc-openapi-specification/blob/main/LICENSE"
    },
    "version": "7.18.2"
  },
  "servers": [
    {
      "url": "https://api.pandadoc.com",
      "description": "Public API"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "Operations for managing documents, including appending content library items and creating document sessions for embedded signing."
    }
  ],
  "paths": {
    "/public/v1/documents?upload": {
      "post": {
        "tags": [
          "Documents"
        ],
        "summary": "Create Document from File Upload",
        "description": "## Create from an upload\n> See the [Create from PDF](https://developers.pandadoc.com/docs/create-document-from-file) tutorial for the usage specifics and sample PDF files.\n\n**Note**: A file you upload is not stored in your PandaDoc account, so you have to upload it with every request.\n",
        "operationId": "createDocumentFromUpload",
        "parameters": [
          {
            "name": "editor_ver",
            "in": "query",
            "deprecated": true,
            "schema": {
              "type": "string"
            },
            "example": "ev2",
            "description": "Set this parameter as `ev1` if you want to create a document from PDF with Classic Editor when both editors are enabled for the workspace."
          },
          {
            "name": "use_form_field_properties",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "true",
            "description": "Set this parameter as `yes` or `1` or `true` (only when upload pdf with form fields) if you want to  respect form fields properties, like `required`."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Binary PDF File"
                  },
                  "data": {
                    "$ref": "#/components/schemas/DocumentCreateByPdfRequest"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentCreateResponse"
                },
                "examples": {
                  "Document from File Upload": {
                    "value": {
                      "id": "D3okRfgHRX7NEhavcACReB",
                      "name": "Document from Template",
                      "status": "document.uploaded",
                      "date_created": "2024-07-04T19:27:14.927317Z",
                      "date_modified": "2024-07-04T19:27:14.927317Z",
                      "expiration_date": null,
                      "version": null,
                      "uuid": "D3okRfgHRX7NEhavcACReB",
                      "links": [
                        {
                          "rel": "status",
                          "href": "https://api.pandadoc.com/public/v1/documents/D3okRfgHRX7NEhavcACReB",
                          "type": "GET"
                        }
                      ],
                      "info_message": "Wait until the status is changed to document.draft. You may use webhooks or poll the Document Status method."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "The `Authorization` header must contain the API key. The value should be prefixed with `API-Key` followed by a space and the actual API key.\n",
        "x-default": "API-Key 3039ba033eb1410caa0a2227158d63c9d6502cd8"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.pandadoc.com/oauth2/authorize",
            "tokenUrl": "https://api.pandadoc.com/oauth2/access_token",
            "refreshUrl": "https://api.pandadoc.com/oauth2/access_token",
            "scopes": {
              "read+write": "Use `read+write` to create, send, delete, and download documents, and `read` to view templates and document details."
            }
          }
        },
        "description": "Send the authenticating user to the PandaDoc OAuth2 request URL. We recommend a button or a link titled\n\"Connect to PandaDoc\" if you are connecting users from a custom application. Users will see the \"Authorize Application\" screen.\nWhen the user clicks \"Authorize\", PandaDoc redirects the user back to your site with an authorization code inside the URL.\n\nhttps://app.pandadoc.com/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=read+write&response_type=code\n\n`client_id` and `redirect_uri` values should match your application settings.\n"
      }
    },
    "schemas": {
      "RecipientDeliveryMethods": {
        "type": "object",
        "nullable": true,
        "properties": {
          "email": {
            "type": "boolean"
          },
          "sms": {
            "type": "boolean"
          }
        }
      },
      "RecipientRedirect": {
        "type": "object",
        "properties": {
          "is_enabled": {
            "type": "boolean",
            "default": false
          },
          "url": {
            "type": "string",
            "nullable": true,
            "default": null,
            "example": "https://example.com",
            "description": "A URL to redirect to after the document is signed."
          }
        },
        "required": [
          "is_enabled",
          "url"
        ]
      },
      "BaseActor": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "example": "user",
            "description": "A recipient's role in the document from the template. A recipient will be added in CC if a role parameter is not provided."
          },
          "signing_order": {
            "type": "integer",
            "example": 1,
            "description": "Set a signing order for a recipient. Learn more: https://developers.pandadoc.com/docs/set-signing-order\n"
          }
        }
      },
      "BaseIdentity": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "nullable": true,
            "example": "josh@example.com",
            "description": "A recipient's email address."
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "example": "+14842634627",
            "description": "A recipient's phone number."
          },
          "first_name": {
            "type": "string",
            "example": "Josh",
            "description": "A recipient's first name. We automatically take the first name from contact data if this field is missed."
          },
          "last_name": {
            "type": "string",
            "example": "Ron",
            "description": "A recipient's last name. We automatically take the last name from contact data if this field is missed."
          }
        }
      },
      "RecipientVerificationPlaceEnum": {
        "description": "Specifies when a recipient must complete the verification process:\n- `before_open` (before opening the document),\n- `before_sign` (before signing the document).\n",
        "type": "string",
        "enum": [
          "before_open",
          "before_sign"
        ]
      },
      "RecipientVerificationSettings": {
        "type": "object",
        "nullable": true,
        "description": "To set up recipient verification, fill in verification_place and specify the type: passcode_verification, phone_verification, kba_verification or id_verification.\n- For passcode_verification, provide the passcode.\n- For phone_verification, provide the phone_number.\n- For kba_verification and id_verification, set the enabled parameter to true.\n",
        "properties": {
          "verification_place": {
            "$ref": "#/components/schemas/RecipientVerificationPlaceEnum"
          },
          "passcode_verification": {
            "type": "object",
            "description": "Sets the passcode.",
            "properties": {
              "passcode": {
                "type": "string",
                "pattern": "^(?=(?:.*[a-zA-Z]){1,})(?=(?:.*[0-9]){1,})^[\\S]{6,100}$",
                "example": "SimpleCode1",
                "description": "Document passcode."
              }
            },
            "required": [
              "passcode"
            ],
            "nullable": true
          },
          "phone_verification": {
            "type": "object",
            "description": "Sets the phone number to send a passcode to.",
            "properties": {
              "phone_number": {
                "type": "string",
                "pattern": "^\\+[1-9]\\d{0,4}\\d{2,14}$",
                "example": "+1234567890",
                "description": "A phone number to send a passcode to."
              }
            },
            "required": [
              "phone_number"
            ]
          },
          "kba_verification": {
            "type": "object",
            "description": "Sets the KBA verification.",
            "properties": {
              "time_limit_sec": {
                "type": "integer",
                "example": 120
              },
              "score_threshold": {
                "type": "integer",
                "example": 80
              },
              "max_attempts_count": {
                "type": "integer",
                "example": 2
              }
            }
          },
          "id_verification": {
            "type": "object",
            "description": "Sets the ID verification.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "example": true
              }
            }
          }
        }
      },
      "CreateDocumentRecipient": {
        "title": "Recipient",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseActor"
          },
          {
            "$ref": "#/components/schemas/BaseIdentity"
          },
          {
            "type": "object",
            "properties": {
              "delivery_methods": {
                "$ref": "#/components/schemas/RecipientDeliveryMethods"
              },
              "redirect": {
                "$ref": "#/components/schemas/RecipientRedirect"
              },
              "type": {
                "type": "string",
                "example": "recipient",
                "enum": [
                  "recipient"
                ]
              },
              "verification_settings": {
                "$ref": "#/components/schemas/RecipientVerificationSettings"
              }
            }
          }
        ]
      },
      "CreateDocumentRecipientGroup": {
        "title": "RecipientGroup",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseActor"
          },
          {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 120
              },
              "type": {
                "type": "string",
                "example": "recipient_group",
                "enum": [
                  "recipient_group"
                ]
              },
              "members": {
                "type": "array",
                "minLength": 1,
                "items": {
                  "$ref": "#/components/schemas/BaseIdentity"
                }
              }
            },
            "required": [
              "name",
              "type"
            ]
          }
        ]
      },
      "CreateDocumentActor": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/CreateDocumentRecipient"
          },
          {
            "$ref": "#/components/schemas/CreateDocumentRecipientGroup"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "recipient": "#/components/schemas/CreateDocumentRecipient",
            "recipient_group": "#/components/schemas/CreateDocumentRecipientGroup"
          }
        }
      },
      "DocumentCreateByPdfRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "parse_form_fields": {
            "type": "boolean",
            "description": "Set this parameter as `true` if you create a document from a PDF with form fields and as `false` if you upload a PDF with field tags."
          },
          "fields": {
            "type": "object",
            "description": "Set specific values to the fields. This object maps merge field names to their corresponding values.\n\nEach key represents a merge field name, and each value is an object containing the data to populate that field with. The structure allows you to pre-populate various field types including text inputs, checkboxes, dropdowns, and date fields.\n\n**Key Points:**\n- Keys must match the exact merge field names from your template or file.\n- Values must be wrapped in an object with a `value` property.\n- Supported value types: string, number, boolean.\n- Date fields should use RFC 3339 format (e.g., '2019-12-31T00:00:00.000Z').\n- Signature fields cannot be pre-filled.\n\n**Example Usage:**\n- Text field: `\"CustomerName\": {\"value\": \"John Doe\"}`\n- Checkbox: `\"AgreeToTerms\": {\"value\": true}`\n- Date field: `\"DeliveryDate\": {\"value\": \"2019-12-31T00:00:00.000Z\"}`\n",
            "example": {
              "Like": {
                "value": true
              },
              "Delivery": {
                "value": "Same Day Delivery"
              },
              "Date": {
                "value": "2019-12-31T00:00:00.000Z"
              }
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "value": {
                  "description": "The value to pre-fill the field with. The type of the value depends on the field type in the template.\nFor example, for a checkbox field, you can pass a boolean value, and for a date field, you can pass a date string in RFC 3339 format (e.g., 2019-12-31T00:00:00.000Z).\n",
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    }
                  ]
                },
                "role": {
                  "type": "string",
                  "description": "Assign this field to a recipient role. The role must be present in the `recipients` list.\n",
                  "example": "user"
                }
              },
              "required": [
                "value"
              ]
            }
          },
          "name": {
            "type": "string",
            "description": "Name the document you are creating.",
            "example": "API Sample Document from PandaDoc Template"
          },
          "folder_uuid": {
            "type": "string",
            "example": "QMDSzwabfFzTgjW4kUijqQ",
            "description": "ID of the folder where the created document should be stored."
          },
          "owner": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "example": "john.doe@example.com"
              },
              "membership_id": {
                "type": "string",
                "example": "QMDSzwabfFzTgjW6KijHyu"
              }
            },
            "description": "The owner of the document. Pass either `email` or `membership_id` of the user in the workspace.",
            "example": {
              "membership_id": "QMDSzwabfFzTgjW6KijHyu"
            }
          },
          "recipients": {
            "type": "array",
            "description": "The list of recipients to whom the document will be sent. Either `email` or `phone` is required. Specifying the `role` assigns all matching fields to the recipient or group. If `first_name` and `last_name` are not specified, the system looks them up in the workspace contacts list using the `email` or `phone number`. If `first_name` and `last_name` are provided, they override the existing contact's data.",
            "items": {
              "$ref": "#/components/schemas/CreateDocumentActor"
            }
          },
          "tokens": {
            "type": "array",
            "description": "Also known as variables. Pass values for the variables in the template to render them into the created document or make them available for insertion later.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "Client.CompanyName"
                },
                "value": {
                  "type": "string",
                  "example": "PandaDoc"
                }
              },
              "required": [
                "name",
                "value"
              ]
            }
          },
          "metadata": {
            "type": "object",
            "nullable": true,
            "description": "You can pass any data in a key-value format to associate it with a document. Searching by metadata is available in the List Documents endpoint and is also included in the Document Details response.",
            "example": {
              "lead_id": "1234567",
              "lead_source": "PandaDoc"
            }
          },
          "tags": {
            "type": "array",
            "description": "Mark your document with one or more tags. Tags are displayed in the UI, and you can filter by tags in the List Documents endpoint.",
            "items": {
              "type": "string"
            },
            "example": [
              "created_via_api",
              "test_document",
              "created_from_source"
            ]
          }
        }
      },
      "DocumentStatusEnum": {
        "type": "string",
        "enum": [
          "document.draft",
          "document.sent",
          "document.completed",
          "document.uploaded",
          "document.error",
          "document.viewed",
          "document.waiting_approval",
          "document.approved",
          "document.rejected",
          "document.waiting_pay",
          "document.paid",
          "document.voided",
          "document.declined",
          "document.external_review"
        ],
        "example": "document.draft"
      },
      "DocumentCreateResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "cKbJ7uay3cEGtsKuGPwYGX"
          },
          "name": {
            "type": "string",
            "example": "API Sample Document from PandaDoc Template"
          },
          "status": {
            "$ref": "#/components/schemas/DocumentStatusEnum"
          },
          "date_created": {
            "type": "string",
            "example": "2021-10-08T11:06:32.337395Z"
          },
          "date_modified": {
            "type": "string",
            "example": "2021-10-08T11:06:32.337395Z"
          },
          "expiration_date": {
            "type": "string",
            "nullable": true,
            "example": "2021-10-08T11:06:32.337395Z"
          },
          "version": {
            "type": "string",
            "nullable": true,
            "example": "EV2"
          },
          "uuid": {
            "type": "string",
            "example": "cKbJ7uay3cEGtsKuGPwYGX"
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "example": "status"
                },
                "href": {
                  "type": "string",
                  "example": "https://api.pandadoc.com/public/v1/documents/jzjCfYgKQYm2u9ctwN6io4"
                },
                "type": {
                  "type": "string",
                  "example": "GET"
                }
              }
            }
          },
          "info_message": {
            "type": "string",
            "example": "You need to poll the Document Status method until the status will be changed to document.draft"
          }
        }
      }
    },
    "responses": {
      "401": {
        "description": "Authentication error",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "type": {
                  "type": "string",
                  "example": "authentication_error"
                },
                "detail": {
                  "type": "string",
                  "example": "Authentication credentials were not provided."
                }
              }
            }
          }
        }
      },
      "429": {
        "description": "Too Many Requests",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "type": {
                  "type": "string",
                  "example": "throttled"
                },
                "detail": {
                  "type": "string",
                  "example": "Request was throttled."
                }
              }
            }
          }
        }
      },
      "400ValidationError": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "type": {
                  "type": "string",
                  "example": "validation_error"
                },
                "detail": {
                  "type": "object",
                  "example": {
                    "count": [
                      "A valid integer is required."
                    ],
                    "order_by": [
                      "value is not a valid choice."
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```