--- title: "Create Document from Markdown File Upload" method: POST path: "/public/v1/documents?upload-markdown" tags: ["Documents"] --- # Create Document from Markdown File Upload `POST /public/v1/documents?upload-markdown` ## Request - Base URL: `https://api.pandadoc.com` - URL: `https://api.pandadoc.com/public/v1/documents?upload-markdown` - Auth: one of: - API key in header `Authorization` - OAuth 2 - Authorization code: `https://app.pandadoc.com/oauth2/authorize` - Token URL: `https://api.pandadoc.com/oauth2/access_token` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Create from a Markdown upload Upload a Markdown (`.md`) file to create a new document. The file content will be converted into a PandaDoc document. **Note**: A file you upload is not stored in your PandaDoc account, so you have to upload it with every request. > **Alpha:** Markdown file upload is currently in alpha. > This functionality may change or be removed without notice. ## Request body `multipart/form-data` - object - `file` string, binary: The Markdown file to upload. Accepted content types: `text/markdown`, `text/x-markdown`. - `data` DocumentCreateByMarkdownRequest: Request body for creating a document from an uploaded Markdown file. > **Alpha:** Markdown file upload is currently in alpha. This functionality may change or be removed without notice. - `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. - `fields_mapping` object: Map recipient roles to document field identifiers. Each key is a recipient role name (must match a `role` defined in `recipients`), and the value is a list of field identifiers to assign to that recipient. Field identifiers reference fields created from the Markdown content. The system validates that all specified field identifiers exist in the document and that all referenced roles are present in the `recipients` list. ## 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 - `429`: Too Many Requests ## Changes - **2026-11-03** `b9a306b1a421`: 1 info - endpoint added [Operation history](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/changes/public/v1/documents%3Fupload-markdown/post.md) --- [API](https://skmtc.dev/pandadoc/apis/pandadoc-public-api.md) - [All operations](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pandadoc/apis/pandadoc-public-api/revisions/b9a306b1a421?raw)