--- title: "Create Document" method: POST path: "/public/v1/documents" tags: ["Documents"] --- # Create Document `POST /public/v1/documents` ## Create from a template > See the [Create document from template](https://developers.pandadoc.com/docs/create-document-from-template) tutorial for details on how to use this endpoint, as well as a sample template. ## Create from a URL > See the [Create from public PDF](https://developers.pandadoc.com/docs/create-and-send-a-document-from-a-publicly-available-pdf) guide for info about roles and fields, as well as PDF examples. ## Query parameters - `editor_ver` string - `use_form_field_properties` string ## Request body - union - DocumentCreateByTemplateRequest - `template_uuid` string, required — 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. - `fields` object — Set specific values to the fields. This object maps merge field names to their corresponding values. Each 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. **Key Points:** - Keys must match the exact merge field names from your template or file. - Values must be wrapped in an object with a `value` property. - Supported value types: string, number, boolean. - Date fields should use RFC 3339 format (e.g., '2019-12-31T00:00:00.000Z'). - Signature fields cannot be pre-filled. **Example Usage:** - Text field: `"CustomerName": {"value": "John Doe"}` - Checkbox: `"AgreeToTerms": {"value": true}` - Date field: `"DeliveryDate": {"value": "2019-12-31T00:00:00.000Z"}` - `images` object[] — You can pass a list of images to image blocks (one image in one block) for replacement. - `urls` string[], required - `name` string, required - `pricing_tables` PricingTableRequest[] — 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. - `name` string, required - `data_merge` boolean — When set to true all field names in data rows must be passed as external names defined in the template. - `options` object - `sections` object[] - `title` string, required - `default` boolean - `multichoice_enabled` boolean - `rows` object[] - `options` object - `qty_editable` boolean - `optional_selected` boolean - `optional` boolean - `data` object - `custom_fields` object - `tables` TableRequest[] — Information to construct or populate a table can be passed when creating a document. Keep in mind that this is an array, so multiple table objects can be passed to a document. - `name` string, required — Name of the table. - `data` object, required - `sections` object[], required - `header` TableCell[], required - `text` string, required — Cell text. - `col_span` integer, nullable — Represents how many columns the cell occupies. - `row_span` integer, nullable — Represents the number of rows the cell occupies. - `rows` array[], required - TableCell[] - … - `texts` object[] — You can pass a list of rich text values to pre-fill text blocks in a template. This is useful for inserting dynamic content like introductions or terms and conditions. Markdown is supported. - `name` string, required — The name of the Text Block to update. This name is defined in the template. - `data` string, required — The text content to be inserted into the block. Supports markdown. - `detect_title_variables` boolean — Set this parameter as true if you want to detect title variables in the document. - `content_placeholders` object[] — 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. - `content_library_items` object[] - `id` string, required — Content library item id - `fields` object - `pricing_tables` PricingTableRequest[] - `name` string, required - `data_merge` boolean — When set to true all field names in data rows must be passed as external names defined in the template. - `options` object - `sections` object[] - `title` string, required - `default` boolean - `multichoice_enabled` boolean - `rows` object[] - … - `recipients` object[] - `email` string, nullable - `phone` string, nullable - `delivery_methods` RecipientDeliveryMethods, nullable - `email` boolean - `sms` boolean - `first_name` string - `last_name` string - `role` string - `signing_order` integer, nullable - `redirect` RecipientRedirect - `is_enabled` boolean, required - `url` string, nullable, required — A URL to redirect to after the document is signed. - `block_id` string, required — Content placeholder block id - `name` string — Name the document you are creating. - `folder_uuid` string — ID of the folder where the created document should be stored. - `owner` object — The owner of the document. Pass either `email` or `membership_id` of the user in the workspace. - `email` string - `membership_id` string - `recipients` CreateDocumentActor[], required — 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. - union - CreateDocumentRecipient - `role` string, nullable — 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` integer, nullable — Set a signing order for a recipient. Learn more: https://developers.pandadoc.com/docs/set-signing-order - `email` string, nullable — A recipient's email address. - `phone` string, nullable — A recipient's phone number. - `first_name` string, nullable — A recipient's first name. We automatically take the first name from contact data if this field is missed. - `last_name` string, nullable — A recipient's last name. We automatically take the last name from contact data if this field is missed. - `delivery_methods` RecipientDeliveryMethods, nullable - `email` boolean - `sms` boolean - `redirect` RecipientRedirect - `is_enabled` boolean, required - `url` string, nullable, required — A URL to redirect to after the document is signed. - `type` 'recipient' - `verification_settings` RecipientVerificationSettings — To set up recipient verification, provide verification_place (required) and exactly one verification type: passcode_verification, phone_verification, kba_verification, id_verification, or email_otp_verification. All other verification type fields must be null. Providing more than one verification type returns a 400 error. - For passcode_verification, provide the passcode. - For phone_verification, provide the phone_number. - For email_otp_verification, provide the email. - For kba_verification and id_verification, set the enabled parameter to true. - `verification_place` 'before_open' | 'before_sign' — Specifies when a recipient must complete the verification process: - `before_open` (before opening the document), - `before_sign` (before signing the document). - `passcode_verification` object, nullable — Sets the passcode. - … - `phone_verification` object, nullable — Sets the phone number to send a passcode to. - … - `kba_verification` object, nullable — Sets the KBA verification. - … - `id_verification` object, nullable — Sets the ID verification. - … - `email_otp_verification` object, nullable — Sets the email address to send a one-time passcode to. - … - CreateDocumentRecipientGroup - `role` string, nullable — 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` integer, nullable — Set a signing order for a recipient. Learn more: https://developers.pandadoc.com/docs/set-signing-order - `name` string, required - `type` 'recipient_group', required - `members` BaseIdentity[] - `email` string, nullable — A recipient's email address. - `phone` string, nullable — A recipient's phone number. - `first_name` string, nullable — A recipient's first name. We automatically take the first name from contact data if this field is missed. - `last_name` string, nullable — A recipient's last name. We automatically take the last name from contact data if this field is missed. - `tokens` object[] — 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. - `name` string, required - `value` string, required - `metadata` object, nullable — 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. - `tags` string[] — 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. - DocumentCreateByPdfUrlRequest — Use a URL to create a document. - `url` string, required — Secure (HTTPS) and publicly accessible URL to the PDF document. - `parse_form_fields` boolean — 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` object — Set specific values to the fields. This object maps merge field names to their corresponding values. Each 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. **Key Points:** - Keys must match the exact merge field names from your template or file. - Values must be wrapped in an object with a `value` property. - Supported value types: string, number, boolean. - Date fields should use RFC 3339 format (e.g., '2019-12-31T00:00:00.000Z'). - Signature fields cannot be pre-filled. **Example Usage:** - Text field: `"CustomerName": {"value": "John Doe"}` - Checkbox: `"AgreeToTerms": {"value": true}` - Date field: `"DeliveryDate": {"value": "2019-12-31T00:00:00.000Z"}` - `name` string, required — Name the document you are creating. - `folder_uuid` string — ID of the folder where the created document should be stored. - `owner` object — The owner of the document. Pass either `email` or `membership_id` of the user in the workspace. - `email` string - `membership_id` string - `recipients` CreateDocumentActor[] — 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. - union - CreateDocumentRecipient - `role` string, nullable — 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` integer, nullable — Set a signing order for a recipient. Learn more: https://developers.pandadoc.com/docs/set-signing-order - `email` string, nullable — A recipient's email address. - `phone` string, nullable — A recipient's phone number. - `first_name` string, nullable — A recipient's first name. We automatically take the first name from contact data if this field is missed. - `last_name` string, nullable — A recipient's last name. We automatically take the last name from contact data if this field is missed. - `delivery_methods` RecipientDeliveryMethods, nullable - `email` boolean - `sms` boolean - `redirect` RecipientRedirect - `is_enabled` boolean, required - `url` string, nullable, required — A URL to redirect to after the document is signed. - `type` 'recipient' - `verification_settings` RecipientVerificationSettings — To set up recipient verification, provide verification_place (required) and exactly one verification type: passcode_verification, phone_verification, kba_verification, id_verification, or email_otp_verification. All other verification type fields must be null. Providing more than one verification type returns a 400 error. - For passcode_verification, provide the passcode. - For phone_verification, provide the phone_number. - For email_otp_verification, provide the email. - For kba_verification and id_verification, set the enabled parameter to true. - `verification_place` 'before_open' | 'before_sign' — Specifies when a recipient must complete the verification process: - `before_open` (before opening the document), - `before_sign` (before signing the document). - `passcode_verification` object, nullable — Sets the passcode. - … - `phone_verification` object, nullable — Sets the phone number to send a passcode to. - … - `kba_verification` object, nullable — Sets the KBA verification. - … - `id_verification` object, nullable — Sets the ID verification. - … - `email_otp_verification` object, nullable — Sets the email address to send a one-time passcode to. - … - CreateDocumentRecipientGroup - `role` string, nullable — 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` integer, nullable — Set a signing order for a recipient. Learn more: https://developers.pandadoc.com/docs/set-signing-order - `name` string, required - `type` 'recipient_group', required - `members` BaseIdentity[] - `email` string, nullable — A recipient's email address. - `phone` string, nullable — A recipient's phone number. - `first_name` string, nullable — A recipient's first name. We automatically take the first name from contact data if this field is missed. - `last_name` string, nullable — A recipient's last name. We automatically take the last name from contact data if this field is missed. - `tokens` object[] — 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. - `name` string, required - `value` string, required - `metadata` object, nullable — 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. - `tags` string[] — 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. ## Response `201` OK - DocumentCreateResponse - `id` string - `name` string - `status` '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' | 'document.scheduled' - `date_created` string - `date_modified` string - `expiration_date` string, nullable - `version` string, nullable - `uuid` string - `links` object[] - `rel` string - `href` string - `type` string - `info_message` string ## Other responses - `400` — Bad Request - `401` — Authentication error - `403` — Permission error - `429` — Too Many Requests --- [API](https://skmtc.net/pandadoc/apis/pandadoc-public-api.md) · [All operations](https://skmtc.net/pandadoc/apis/pandadoc-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pandadoc/pandadoc-public-api/versions/0c2b70be3fb0/schema)