# Document Status
It is useful to request document status to ensure a document is in the expected state before calling additional API methods.
### Required Document Statuses
Here are some common methods and the `document.status` required to proceed:
| API Method | Required Document State |
| :------------------- | :---------------------- |
| Send A Document | `document.draft` |
| Get Document Details | `document.draft` |
| Embed A Document | `document.sent` |
| Download A Document | `document.completed` |
> 📘 Polling vs Webhooks
>
> If you are using the `GET` document status endpoint for [**polling**](https://en.wikipedia.org/wiki/Polling_(computer_science)), we also support and recommend using **webhooks** for event-driven needs:
### Available Document Statuses
The following is a complete list of all possible document statuses returned:
| Document Status | Status Description |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document.uploaded` | The document has just been created or uploaded. It is in processing and will be in `document.draft` state soon. |
| `document.error` | The document creation has failed. This status is terminal, you should stop polling after getting it.
| `document.draft` | The document is in a draft state. All aspects of the document can be edited in this state. Our API does not support edits after the document has been created, but it can still be edited manually on |
| `document.sent` | The document has been "sealed" and optionally sent. No further document edits can occur except for document recipient(s) filling out or signing the document. |
| `document.viewed` | Document recipient(s) have viewed the sent document. |
| `document.waiting_approval` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and has not yet been approved. |
| `document.rejected` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and was rejected. |
| `document.approved` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and was approved. |
| `document.waiting_pay` | The document has a [Stripe payment](https://support.pandadoc.com/en/articles/9714942-stripe-checkout-payments) option and is awaiting payment. |
| `document.paid` | The document has a [Stripe payment](https://support.pandadoc.com/en/articles/9714942-stripe-checkout-payments) option and was paid. |
| `document.completed` | The document has been completed by all recipients. |
| `document.voided` | The document expired and is no longer available for completion or signature. |
| `document.declined` | The document was [manually marked](https://support.pandadoc.com/en/articles/9714842-manually-change-document-status) as "Declined" |
| `document.external_review` | The document is reviewed by it's recipient using Suggest Edit feature |
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "PandaDoc Public API",
"description": "PandaDoc API spans a broad range of functionality to help you build incredible documents automation experiences inside your product.\n\nPandaDoc API is organized around REST. Our API has predictable resource-oriented URLs and uses standard HTTP response codes, authentication, and verbs.\n\n## Getting started\n\nYou can start testing PandaDoc API with a sandbox key on our [Enterprise](https://www.pandadoc.com/pricing/) plan, either active or in trial.\n\nGenerate your [sandbox key](https://developers.pandadoc.com/reference/sandbox-key) on the Developer Dashboard with predefined [rate limits](https://developers.pandadoc.com/reference/limits). Or contact our solutions expert if you work with high-transaction volumes.\n\n## Guides\n\nIf you’re just getting started with PandaDoc, you may want to jump straight into one of our [getting started guides](https://developers.pandadoc.com/docs/getting-started) for the feature you’re most interested in, whether that’s:\n\n- [Create from template](https://developers.pandadoc.com/docs/create-send-document),\n- [Upload and send a local PDF](https://developers.pandadoc.com/docs/upload-and-send-a-local-pdf),\n- or [Listening for changes in document status](https://developers.pandadoc.com/docs/listen-document-status-changes).\n\nWe also recommend you to discover our dynamic content generation on a fly: [Create from a template with content placeholder](https://developers.pandadoc.com/docs/create-with-content-placeholders-from-template).\n",
"termsOfService": "https://www.pandadoc.com/master-services-agreement/",
"contact": {
"name": "PandaDoc API Support",
"url": "https://developers.pandadoc.com/",
"email": "api-track@pandadoc.com"
},
"license": {
"name": "MIT",
"url": "https://github.com/PandaDoc/pandadoc-openapi-specification/blob/main/LICENSE"
},
"version": "7.18.2"
},
"servers": [
{
"url": "https://api.pandadoc.com",
"description": "Public API"
}
],
"security": [
{
"apiKey": []
},
{
"oauth2": []
}
],
"tags": [
{
"name": "Documents",
"description": "Operations for managing documents, including appending content library items and creating document sessions for embedded signing."
}
],
"paths": {
"/public/v1/documents/{id}": {
"get": {
"tags": [
"Documents"
],
"summary": "Document Status",
"operationId": "statusDocument",
"description": "It is useful to request document status to ensure a document is in the expected state before calling additional API methods. \n\n### Required Document Statuses\n\nHere are some common methods and the `document.status` required to proceed:\n\n| API Method | Required Document State |\n| :------------------- | :---------------------- |\n| Send A Document | `document.draft` |\n| Get Document Details | `document.draft` |\n| Embed A Document | `document.sent` |\n| Download A Document | `document.completed` |\n\n> 📘 Polling vs Webhooks\n> \n> If you are using the `GET` document status endpoint for [**polling**](https://en.wikipedia.org/wiki/Polling_(computer_science)), we also support and recommend using **webhooks** for event-driven needs: \n\n### Available Document Statuses\n\nThe following is a complete list of all possible document statuses returned:\n\n| Document Status | Status Description |\n| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `document.uploaded` | The document has just been created or uploaded. It is in processing and will be in `document.draft` state soon. |\n| `document.error` | The document creation has failed. This status is terminal, you should stop polling after getting it.\n| `document.draft` | The document is in a draft state. All aspects of the document can be edited in this state. Our API does not support edits after the document has been created, but it can still be edited manually on |\n| `document.sent` | The document has been \"sealed\" and optionally sent. No further document edits can occur except for document recipient(s) filling out or signing the document. |\n| `document.viewed` | Document recipient(s) have viewed the sent document. |\n| `document.waiting_approval` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and has not yet been approved. |\n| `document.rejected` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and was rejected. |\n| `document.approved` | The document has an [automatic approval workflow](https://support.pandadoc.com/en/articles/9714799-approval-workflow) and was approved. |\n| `document.waiting_pay` | The document has a [Stripe payment](https://support.pandadoc.com/en/articles/9714942-stripe-checkout-payments) option and is awaiting payment. |\n| `document.paid` | The document has a [Stripe payment](https://support.pandadoc.com/en/articles/9714942-stripe-checkout-payments) option and was paid. |\n| `document.completed` | The document has been completed by all recipients. |\n| `document.voided` | The document expired and is no longer available for completion or signature. |\n| `document.declined` | The document was [manually marked](https://support.pandadoc.com/en/articles/9714842-manually-change-document-status) as \"Declined\" |\n| `document.external_review` | The document is reviewed by it's recipient using Suggest Edit feature |\n",
"parameters": [
{
"examples": {
"Document processing after create": {
"value": "fANp5wW5EwY7AkiTkTGekZ"
},
"Document in draft": {
"value": "XjV64iXRJMerjSpk428QSF"
}
},
"name": "id",
"in": "path",
"schema": {
"type": "string"
},
"required": true,
"description": "Specify document ID."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentStatusResponse"
},
"examples": {
"Document processing after create": {
"value": {
"id": "fANp5wW5EwY7AkiTkTGekZ",
"name": "Document from file",
"status": "document.uploaded",
"date_created": "2024-07-02T16:21:57.510203Z",
"date_modified": "2024-07-02T16:21:57.708251Z",
"expiration_date": null,
"version": null,
"uuid": "fANp5wW5EwY7AkiTkTGekZ"
}
},
"Document in draft": {
"value": {
"id": "XjV64iXRJMerjSpk428QSF",
"name": "Document from template",
"status": "document.draft",
"date_created": "2024-03-19T12:59:52.848666Z",
"date_modified": "2024-03-19T12:59:53.957830Z",
"date_completed": null,
"expiration_date": null,
"version": "2",
"uuid": "XjV64iXRJMerjSpk428QSF"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"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": {
"DocumentStatusResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "msFYActMfJHqNTKH8YSvF1"
},
"name": {
"type": "string",
"example": "API Sample Document from PandaDoc Template"
},
"status": {
"type": "string",
"example": "document.viewed"
},
"date_created": {
"type": "string",
"example": "2017-07-06T08:42:13.836022Z"
},
"date_modified": {
"type": "string",
"nullable": true,
"example": "2017-08-04T02:21:13.963750Z"
},
"date_completed": {
"type": "string",
"nullable": true,
"example": "2018-08-03T08:21:38.809868Z"
},
"expiration_date": {
"type": "string",
"nullable": true,
"example": "2018-08-05T08:21:38.809868Z"
},
"version": {
"type": "string",
"nullable": true,
"example": "2"
},
"uuid": {
"type": "string",
"example": "msFYActMfJHqNTKH8YSvF1"
}
}
}
},
"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."
}
}
}
}
}
},
"403": {
"description": "Permission error",
"content": {
"application/json": {
"schema": {
"properties": {
"type": {
"type": "string",
"example": "permission_error"
},
"detail": {
"type": "string",
"example": "You do not have permission to perform this action."
},
"info_message": {
"type": "string",
"description": "Human-readable explanation of the permission error.",
"example": "You are not allowed to send documents outside of your organization"
},
"links": {
"type": "array",
"description": "Optional links related to the error (e.g. a status endpoint).",
"items": {
"type": "object",
"properties": {
"rel": {
"type": "string",
"example": "status"
},
"href": {
"type": "string",
"example": "https://api.pandadoc.com/public/v1/documents/RsXrKarV524iCpjci9CMGa"
},
"type": {
"type": "string",
"example": "POST"
}
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"properties": {
"type": {
"type": "string",
"example": "request_error"
},
"detail": {
"type": "string",
"example": "Not found"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"properties": {
"type": {
"type": "string",
"example": "throttled"
},
"detail": {
"type": "string",
"example": "Request was throttled."
}
}
}
}
}
}
}
}
}
```