# Create Document Section With this endpoint, you can add a new section to an existing PandaDoc document (create a bundle). You can upload a section to the document using a PandaDoc template or a file by URL. > ⏱️ 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. ## Using a PandaDoc template
> 🚧 Current Version Limitations > > Images in sections are currently not supported. > 📘 Pricing tables note > > Each pricing table must have a unique name to populate it with data correctly. A PandaDoc template is a document template created and edited in the PandaDoc web application. Our [help center](https://support.pandadoc.com/en/articles/9714616-save-time-with-a-reusable-template) has further information on PandaDoc templates. If you don't have any PandaDoc Template yet, you can easily create one by clicking [Copy a Sample PandaDoc template](https://app.pandadoc.com/get-this-template/?pt=public_template&pub=eiC3a6qBVfEfbw7VCYgaeN). This will open the PandaDoc application in a new tab, copy the sample template into your account, and create a new document from the template.
## Using a File by URL
Using this endpoint you can add a section to the existing document. 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) > ❗️ Limitations > > * This method does not support multiple documents. > * The maximum supported file size is 50 MB. API returns "413 Request entity too large" in case of bigger files. > * 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). ### 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 | ```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" } } ``` > 📘 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) ### 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 } ] ``` > 📘 Signing order in PandaDoc > > The following article explains how to use signing order: [How to use signing order](https://support.pandadoc.com/en/articles/9714771-signing-order) ### 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": { "post": { "tags": [ "Document Sections (Bundles)" ], "summary": "Create Document Section", "operationId": "uploadSection", "description": "With this endpoint, you can add a new section to an existing PandaDoc document (create a bundle).\n\nYou can upload a section to the document using a PandaDoc template or a file by URL.\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## Using a PandaDoc template\n\n
\n\n > 🚧 Current Version Limitations\n > \n > Images in sections are currently not supported.\n\n > 📘 Pricing tables note\n > \n > Each pricing table must have a unique name to populate it with data correctly.\n\n A PandaDoc template is a document template created and edited in the PandaDoc web application. Our [help center](https://support.pandadoc.com/en/articles/9714616-save-time-with-a-reusable-template) has further information on PandaDoc templates. \n\n If you don't have any PandaDoc Template yet, you can easily create one by clicking [Copy a Sample PandaDoc template](https://app.pandadoc.com/get-this-template/?pt=public_template&pub=eiC3a6qBVfEfbw7VCYgaeN). This will open the PandaDoc application in a new tab, copy the sample template into your account, and create a new document from the template.\n
\n\n## Using a File by URL\n\n
\n \n Using this endpoint you can add a section to the existing document. 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 > ❗️ Limitations\n > \n > * This method does not support multiple documents.\n > * The maximum supported file size is 50 MB. API returns \"413 Request entity too large\" in case of bigger files.\n > * 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 ### PDF Form Fields\n\n 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.\n\n 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.\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\n 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.\n\n 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.\n\n Here 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 #### 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 ```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 > 📘 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 ### Signing order\n\n Set 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 > 📘 Signing order in PandaDoc\n >\n > The following article explains how to use signing order: [How to use signing order](https://support.pandadoc.com/en/articles/9714771-signing-order)\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 \n
\n", "parameters": [ { "examples": { "Create Document Section from Template": { "value": "CFz2UnLXDck3UJkeGGEuB3" } }, "name": "document_id", "description": "Document ID", "in": "path", "schema": { "type": "string" }, "required": true }, { "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": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/UploadSectionByTemplateRequest" }, { "title": "From PandaDoc Template" } ] }, { "allOf": [ { "$ref": "#/components/schemas/UploadSectionRequest" }, { "title": "From File By Url", "properties": { "url": { "type": "string", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "description": "Secure (HTTPS) and publicly accessible URL to the PDF document." } }, "required": [ "url" ] } ] } ] }, "examples": { "Create Document Section From Template": { "value": { "name": "New section from template", "template_uuid": "hryJY9mqYZHjQCYQuSjRQg", "recipients": [ { "role": "Client", "email": "client@pandadoc.com" }, { "role": "Sender", "email": "sender@pandadoc.com" } ] } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSectionResponse" }, "examples": { "Create Document Section From Template": { "value": { "uuid": "LQ6cUT7xevPLUEgJeF8Zrm", "document_uuid": "CFz2UnLXDck3UJkeGGEuB3", "status": "document_sections_upload.UPLOADED", "name": "null", "date_created": "2023-08-28T15:48:09.379860Z", "date_modified": "2023-08-28T15:48:09.379860Z", "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": { "PricingTableRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "Pricing Table 1" }, "data_merge": { "type": "boolean", "description": "When set to true all field names in data rows must be passed as external names defined in the template." }, "options": { "type": "object", "example": { "currency": "USD", "Discount": { "type": "absolute", "name": "Global Discount", "value": 10 }, "Tax": { "type": "percent", "name": "Tax First", "value": 15 } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Sample Section" }, "default": { "type": "boolean" }, "multichoice_enabled": { "type": "boolean", "default": false }, "rows": { "type": "array", "items": { "type": "object", "properties": { "options": { "type": "object", "title": "Pricing Table Request Row Options", "properties": { "qty_editable": { "type": "boolean" }, "optional_selected": { "type": "boolean" }, "optional": { "type": "boolean" } } }, "data": { "type": "object", "title": "Pricing Table Request Row Data", "example": { "Name": "Toy Panda", "Description": "Fluffy", "Price": 10, "Cost": 8.5, "QTY": 3, "SKU": "toy_panda", "Discount": { "value": 10, "type": "percent" }, "Tax": { "value": 10, "type": "percent" } } }, "custom_fields": { "type": "object", "example": { "Fluffiness": "5/5" } } } } } }, "required": [ "title" ] } } }, "required": [ "name" ] }, "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" ] }, "UploadSectionByTemplateRequest": { "allOf": [ { "type": "object", "properties": { "template_uuid": { "type": "string", "description": "The ID of a template you want to use. You can copy it from an in app template url such as `https://app.pandadoc.com/a/#/templates/{ID}/content`. A template ID is also obtained by listing templates.", "example": "hryJY9mqYZHjQCYQuSjRQg" }, "pricing_tables": { "type": "array", "description": "Information to construct or populate a pricing table can be passed when creating a document. All product information must be passed when creating a new document. Products stored in PandaDoc cannot be used to populate table rows at this time. Keep in mind that this is an array, so multiple table objects can be passed to a document. Make sure that \"Automatically add products to this table\" is enabled in the PandaDoc template pricing tables you wish to populate via API. Each pricing table must have a unique name to populate it with data correctly.", "items": { "$ref": "#/components/schemas/PricingTableRequest" } }, "content_placeholders": { "type": "array", "description": "You may replace Content Library Item Placeholders with a few content library items each and pre-fill fields/variables values, pricing table items, and assign recipients to roles from there.", "items": { "type": "object", "properties": { "content_library_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "9d9k7VtSQ5KCXfsUQv4GxE" }, "fields": { "type": "object" }, "pricing_tables": { "type": "array", "items": { "$ref": "#/components/schemas/PricingTableRequest" } }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "example": "josh@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+14842634627" }, "delivery_methods": { "$ref": "#/components/schemas/RecipientDeliveryMethods" }, "first_name": { "type": "string", "example": "Josh" }, "last_name": { "type": "string", "example": "Ron" }, "role": { "type": "string", "example": "user" }, "signing_order": { "type": "integer", "example": 1, "nullable": true }, "redirect": { "$ref": "#/components/schemas/RecipientRedirect" } } } } }, "required": [ "id" ] } }, "block_id": { "type": "string", "example": "Content Placeholder 1" } }, "required": [ "block_id" ] } }, "fields": { "type": "object", "description": "You can pass a list of fields/values to pre-fill fields used in a template. Note that the Signature field can't be pre-filled. Field values with the same merge id will override field values of the whole document by default, unless you set the merge_field_scope=upload query parameter.", "example": { "Like": { "value": "true" }, "Delivery": { "value": "Same Day Delivery" }, "Date": { "value": "2019-12-31T00:00:00.000Z" } } } }, "required": [ "template_uuid" ] }, { "$ref": "#/components/schemas/UploadSectionBase" } ] }, "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." ] } } } } } } } } } } ````