# Create Document Section from File Upload With this endpoint, you can add a new section to an existing PandaDoc document (create a bundle). The section is created from a file you upload. The file can be a PDF, DocX, or RTF. > šŸ“˜ We've prepared two samples that you can use to test the request. > Download them here: > > - [Download a Sample PDF with Form Fields](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf) > - [Download a Sample PDF with Field Tags](https://5132871.fs1.hubspotusercontent-na1.net/hubfs/5132871/SamplePandaDocPdf_FieldTags_updated.pdf) > šŸš§ Usage specifics > > 1. This method uses a `multipart/form-data` request type instead of the `application/json` typically found in the PandaDoc API. This is to accommodate the upload of the included document. > 2. You can send a URL instead of a file in the document creation request. > In this case, you need to use the `application/json` content type and add the URL parameter in the body request. As an example, see [Create from public PDF](https://developers.pandadoc.com/docs/create-and-send-a-document-from-a-publicly-available-pdf) guide for more details. > 3. A file you upload is not stored in your PandaDoc account, so you have to upload it with every request. > ā—ļø Limitations > > 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 a PDF with encrypted files (to check whether a file is encrypted or not, try Get info -> Secure: Password Encrypted). > ā±ļø Document Section creation is a non-blocking (asynchronous) operation > > The document creation process may take some time. > > With a successful request, you receive a response with the created upload ID and status `document_sections_upload.uploaded`. After processing completes on our servers, usually a few seconds, the document moves to the `document_sections_upload.PROCESSED` status. ## 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 section 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**](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf) ## PDF/DocX/RTF Field Tags This parsing format allows a word processor such as [Microsoft Word](https://support.office.com/en-us/article/Save-as-PDF-d85416c5-7d77-4fd6-a216-6f4bf7c7c110?ui=en-US&rs=en-US&ad=US) or [Google Docs](https://support.google.com/drive/answer/2423534?co=GENIE.Platform%3DDesktop&hl=en) 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: ![](https://files.readme.io/38afedf-ex3.png "ex3.png") [**Download a Sample PDF with Field Tags**](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FieldTags.pdf)
### PDF Field Tag Key ![](https://files.readme.io/a81fbf1-field-tag-structure.png "field-tag-structure.png") | Number | Key | Description | Example | | :----- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- | | 1 | `fieldType` | Field type from the table documented below | `signature`, or `s` for shorthand | | 2 | `*` | Optional `*` denotes the field is not required | `*` | | 3 | `role` | Role 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` | | 4 | `optId` | Optional 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 Type | Short Notation | Is PandaDoc Field | | :---------- | :------------- | :---------------- | | `textfield` | `t` | Field | | `checkbox` | `c` | Field | | `signature` | `s` | Field | | `date` | `d` | Field | | `initials` | `i` | Field | | `dropdown` | `dd` | Field | > šŸ“˜ Fields in PandaDoc > > The following article explains how to use Fields: [Everything you need to know about Fields](https://support.pandadoc.com/en/articles/9714583-fields) ```json Field Tags Example "fields": { "textfield": { "value": "Jane", "role": "user" }, "dropdown": { "value": "opt1", "role": "user", "options":[ "opt1", "opt2", "opt3" ] }, "checkbox": { "value": true, "role": "user" }, "date":{ "value": "2022-05-20", "role": "user" }, "signature": { "value": "", "role": "user" } } ```
## Signing order Set a signing order for document section sections created from a file. ```json "recipients": [ { "email": "josh@example.com", "first_name": "Josh", "last_name": "Ron", "role": "user", "signing_order": 1 } ] ``` ## Error handling | Error description | Type | Root cause | |---|---|---| | Document version 1 is not supported. | Validation errors: Form fields | The creation document section is supported only for document version 2 | | PDF content hasn't been processed: document is broken or locked | Processing errors: Failed to process document content | Document 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 support | Processing errors: Field tag / Form field validation error | Doc 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 tags | Role 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 tags | Label 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 role | Validation errors: Field tags | Field 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 payload | Validation errors: Form fields | Role 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 fields | Field ā€˜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 fields | Failed 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 errors | Error 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 errors | Error 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 errors | Content 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} MB | Source errors | The file size has exceeded the allowed limits. An error occurred while trying to download a file that is too large (limit is 50M) | # 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": "Document Sections (Bundles)", "description": "Operations for managing document sections, including retrieving details and upload statuses." } ], "paths": { "/public/v1/documents/{document_id}/sections/uploads?upload": { "post": { "tags": [ "Document Sections (Bundles)" ], "summary": "Create Document Section from File Upload", "operationId": "uploadSectionWithUpload", "description": "With this endpoint, you can add a new section to an existing PandaDoc document (create a bundle). The section is created from a file you upload. The file can be a PDF, DocX, or RTF.\n\n> šŸ“˜ We've prepared two samples that you can use to test the request.\n> Download them here:\n>\n> - [Download a Sample PDF with Form Fields](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf) \n> - [Download a Sample PDF with Field Tags](https://5132871.fs1.hubspotusercontent-na1.net/hubfs/5132871/SamplePandaDocPdf_FieldTags_updated.pdf)\n\n\n> šŸš§ Usage specifics\n> \n> 1. This method uses a `multipart/form-data` request type instead of the `application/json` typically found in the PandaDoc API. This is to accommodate the upload of the included document.\n> 2. You can send a URL instead of a file in the document creation request. \n> In this case, you need to use the `application/json` content type and add the URL parameter in the body request. As an example, see [Create from public PDF](https://developers.pandadoc.com/docs/create-and-send-a-document-from-a-publicly-available-pdf) guide for more details.\n> 3. A file you upload is not stored in your PandaDoc account, so you have to upload it with every request.\n\n> ā—ļø Limitations\n> \n> 1. This method does not support multiple documents.\n> 2. The maximum supported file size is 50 MB. API returns \"413 Request entity too large\" in case of bigger files.\n> 3. PandaDoc does not support creating document from a PDF with encrypted files (to check whether a file is encrypted or not, try Get info -> Secure: Password Encrypted).\n\n> ā±ļø Document Section creation is a non-blocking (asynchronous) operation\n> \n> The document creation process may take some time.\n> \n> With a successful request, you receive a response with the created upload ID and status `document_sections_upload.uploaded`. After processing completes on our servers, usually a few seconds, the document moves to the `document_sections_upload.PROCESSED` status.\n\n## PDF Form Fields\n\nPandaDoc recognizes PDF form fields. To enable this feature, pass the optional `parse_form_fields` value as `true` when making a create document section API call. We support Text fields, Dropdowns, and Signature fields.\n\nIf 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.\n\n[**Download a Sample PDF with Form Fields**](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FormFields.pdf)\n\n## PDF/DocX/RTF Field Tags\n\nThis parsing format allows a word processor such as [Microsoft Word](https://support.office.com/en-us/article/Save-as-PDF-d85416c5-7d77-4fd6-a216-6f4bf7c7c110?ui=en-US&rs=en-US&ad=US) or [Google Docs](https://support.google.com/drive/answer/2423534?co=GENIE.Platform%3DDesktop&hl=en) to prepare a document and save it in PDF, DocX or RTF format.\n\nWithin 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.\n\nHere is an example of how the field tag in a PDF/DocX/RTF is converted to a text field in the PandaDoc document:\n\n![](https://files.readme.io/38afedf-ex3.png \"ex3.png\")\n\n[**Download a Sample PDF with Field Tags**](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FieldTags.pdf)\n\n
\n\n ### PDF Field Tag Key\n\n ![](https://files.readme.io/a81fbf1-field-tag-structure.png \"field-tag-structure.png\")\n\n | Number | Key | Description | Example |\n | :----- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |\n | 1 | `fieldType` | Field type from the table documented below | `signature`, or `s` for shorthand |\n | 2 | `*` | Optional `*` denotes the field is not required | `*` |\n | 3 | `role` | Role 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` |\n | 4 | `optId` | Optional field Id. Specify more information about the field tag within the post request by using this id. | `sigBox17` |\n | 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. | `_____` |\n\n > šŸš§ Role names restrictions\n > \n > Underscores are not supported in role names for a file with a Field Tag.\n\n ### PDF/DocX/RTF Field Tag Supported Types\n\n | Field Type | Short Notation | Is PandaDoc Field |\n | :---------- | :------------- | :---------------- |\n | `textfield` | `t` | Field |\n | `checkbox` | `c` | Field |\n | `signature` | `s` | Field |\n | `date` | `d` | Field |\n | `initials` | `i` | Field |\n | `dropdown` | `dd` | Field |\n\n > šŸ“˜ Fields in PandaDoc\n > \n > The following article explains how to use Fields: [Everything you need to know about Fields](https://support.pandadoc.com/en/articles/9714583-fields)\n\n ```json Field Tags Example\n \"fields\": { \n \"textfield\": { \n \"value\": \"Jane\",\n \"role\": \"user\"\n },\n \"dropdown\": {\n \"value\": \"opt1\",\n \"role\": \"user\",\n \"options\":[\n \"opt1\",\n \"opt2\",\n \"opt3\"\n ]\n },\n \"checkbox\": { \n \"value\": true,\n \"role\": \"user\"\n },\n \"date\":{\n \"value\": \"2022-05-20\",\n \"role\": \"user\"\n },\n \"signature\": { \n \"value\": \"\",\n \"role\": \"user\"\n }\n }\n ```\n\n
\n\n## Signing order\n\nSet a signing order for document section sections created from a file.\n\n```json\n\"recipients\": [ \n { \n \"email\": \"josh@example.com\",\n \"first_name\": \"Josh\",\n \"last_name\": \"Ron\",\n \"role\": \"user\",\n \"signing_order\": 1\n }\n]\n```\n\n## Error handling\n\n| Error description | Type | Root cause |\n|---|---|---|\n| Document version 1 is not supported. | Validation errors: Form fields | The creation document section is supported only for document version 2 |\n| PDF content hasn't been processed: document is broken or locked | Processing errors: Failed to process document content | Document converter service canā€™t process PDF. This may be caused by locked PDF or if itā€™s broken. |\n| Error occurred while parsing PDF field tags. Please try PDF flattening or reach out to support | Processing errors: Field tag / Form field validation error | Doc 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 |\n| No role='{role}' for field tag specified in `recipients` found, roles passed were {roles} | Validation errors: Field tags | Role is invalid. When the role specified in field tag is empty or wasnā€™t provided in a payload for any recipient |\n| 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 tags | Label is invalid. Occurs when **optId** specified in field tag is empty or no field with **name = optId** was provided in a payload |\n| One of field tags in PDF with type='{field}' doesn't have a role | Validation errors: Field tags | Field tag in PDF has no role. One of field tags in PDF with type=% doesn't have a role. |\n| Role for form field with name='{role}' is not provided in payload | Validation errors: Form fields | Role for form field with ā€˜nameā€™ is not provided. Occurs when `role` for form field with name=%sĀ  is not provided in payload |\n| Field for form field with name='{name}' is not specified in payload, available names are {names} | Validation errors: Form fields | Field ā€˜nameā€™ is not specified in payload. Occurs when no field with name = form field name was provided in a payload |\n| No role='{role}' for form field specified in 'recipients' found, roles passed were {roles}\" | Validation errors: Form fields | Failed 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 |\n| Failed to download file from link {url}. | Source errors | Error on attempt to download file.Ā  An error has occurred on an attempt to download file using the provided ā€˜urlā€™ in payload |\n| Failed to download file from link {url} (status code: {status code}) | Source errors | Error 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 |\n| Content type='{type}' is not supported, available types are {types} | Source errors | Content type is not supported.Ā  Content type should be one of the following: PDF, ZIP, doc, docx, RTF |\n| The maximum file size is exceeded, limit is {limit} MB | Source errors | The file size has exceeded the allowed limits. An error occurred while trying to download a file that is too large (limit is 50M) |\n", "parameters": [ { "name": "document_id", "description": "Document ID", "in": "path", "schema": { "type": "string" }, "required": true, "example": "BhVzRcxH9Z2LgfPPGXFUBa" }, { "name": "merge_field_scope", "description": "Determines how the fields are mapped when creating a section.\n * document: Default value. The fields of the entire document are updated.\n * upload: Only the fields from the created section are updated. The merge field is appended with the upload ID.\n", "in": "query", "schema": { "type": "string", "enum": [ "document", "upload" ] }, "example": "document" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Binary PDF/DocX/RTF File." }, "data": { "allOf": [ { "$ref": "#/components/schemas/UploadSectionRequest" }, { "description": "JSON as a multipart/form-data string." } ] } } } } } }, "responses": { "201": { "description": "OK", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadSectionResponse" }, "examples": { "Create Document Section from File Upload": { "value": { "uuid": "HiNXiDJazzufdxErSr5w6n", "name": "My Section", "document_uuid": "Gpzd2nXgFjCSŠ–zhTucci2E", "status": "document_sections_upload.UPLOADED", "date_created": "2024-07-15T08:14:33.050351Z", "date_modified": "2024-07-15T08:14:33.050351Z", "info_message": "You need to poll the Document Sections Upload Status method until the status will be changed to document_sections_upload.PROCESSED" } } } } } }, "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" } } }, "UploadSectionBase": { "type": "object", "properties": { "name": { "type": "string", "description": "Name the document you are creating.", "example": "API Sample Document from PandaDoc Template" }, "recipients": { "type": "array", "description": "The list of recipients you're sending the document to. Every object must contain the `email` parameter. The `role`, `first_name` and `last_name` parameters are optional. If the `role` parameter is passed, a person is assigned all fields matching their corresponding role. If a role was not passed, a person receives a read-only link to view the document. If the `first_name` and `last_name` are not passed, the system does this 1. Creates a new contact, if none exists with the given `email`; or 2. Gets the existing contact with the given `email` that already exists.", "items": { "$ref": "#/components/schemas/CreateDocumentActor" } }, "tokens": { "type": "array", "description": "You may pass a list of tokens/values to pre-fill tokens (variables) used in a template. Name is a token (variable) name in a template. Value is a real value you would like to replace a token (variable) with.\n", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Favorite.Pet" }, "value": { "type": "string", "example": "Panda" } }, "required": [ "name", "value" ] } }, "tags": { "type": "array", "description": "Mark your document with one or several tags.", "items": { "type": "string" }, "example": [ "created_via_api", "test_document", "created_from_source" ] } }, "required": [ "recipients" ] }, "UploadSectionRequest": { "allOf": [ { "type": "object", "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": "If you are upload a section from a PDF with field tags, you can pass a list of the fields you'd like to pre-fill in the document. If you are upload a section from a PDF with form fields, list all the fields and provide the `role` parameter so that the fields are assigned to document recipients. You can provide empty value for the field so that it's not pre-filled: \"value\": \"\". Please note Signature field can't be pre-filled.\n", "example": { "Like": { "value": true }, "Delivery": { "value": "Same Day Delivery" }, "Date": { "value": "2019-12-31T00:00:00.000Z" } } } }, "required": [ "recipients" ] }, { "$ref": "#/components/schemas/UploadSectionBase" } ] }, "UploadSectionStatusEnum": { "type": "string", "enum": [ "document_sections_upload.UPLOADED", "document_sections_upload.PROCESSED", "document_sections_upload.ERROR" ], "example": "document_sections_upload.PROCESSED" }, "UploadSectionResponse": { "type": "object", "properties": { "uuid": { "type": "string", "example": "cKbJ7uay3cEGtsKuGPwYGX" }, "name": { "type": "string", "example": "API Sample Upload Section from PandaDoc Template" }, "document_uuid": { "type": "string", "example": "cKbJ7uay3cEGtsKuGPwYGX" }, "status": { "$ref": "#/components/schemas/UploadSectionStatusEnum" }, "date_created": { "type": "string", "example": "2021-10-08T11:06:32.337395Z" }, "date_modified": { "type": "string", "example": "2021-10-08T11:06:32.337395Z" }, "date_completed": { "type": "string", "nullable": true, "example": "2021-10-08T11:06:32.337395Z" }, "info_message": { "type": "string", "example": "You need to poll the Document Sections Upload Status method until the status will be changed to document_sections_upload.PROCESSED" } } } }, "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." ] } } } } } } } } } } ````