# Update Document

Use the PATCH method to update a PandaDoc document.

> 🚧 Document status
> 
> You can only update a document in the Draft status (`document.draft`). 
> 
> After creating a new document, it usually retains a `document.uploaded` status for 3-5 seconds while the document syncs across PandaDoc servers. When the document is available for further API calls, the document moves to the `document.draft` state. Use [Document Status](https://developers.pandadoc.com/reference/document-status) or Webhooks to check document status.


# 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}": {
      "patch": {
        "tags": [
          "Documents"
        ],
        "summary": "Update Document",
        "operationId": "updateDocument",
        "description": "Use the PATCH method to update a PandaDoc document.\n\n> 🚧 Document status\n> \n> You can only update a document in the Draft status (`document.draft`). \n> \n> After creating a new document, it usually retains a `document.uploaded` status for 3-5 seconds while the document syncs across PandaDoc servers. When the document is available for further API calls, the document moves to the `document.draft` state. Use [Document Status](https://developers.pandadoc.com/reference/document-status) or Webhooks to check document status.\n",
        "parameters": [
          {
            "examples": {
              "Update document": {
                "value": "BhVzRcxH9Z2LgfPPGXFUBa"
              }
            },
            "name": "id",
            "description": "Document ID",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentUpdateRequest"
              },
              "examples": {
                "Update document text blocks": {
                  "value": {
                    "texts": [
                      {
                        "name": "Legal Terms Section",
                        "data": "## Terms of Service\nThis document outlines the terms and conditions. \n- **Acceptance:** By using our service, you agree to these terms.\n"
                      },
                      {
                        "name": "Product Description",
                        "data": "## Product Description\nGeneral description of the product.\n"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No content"
          },
          "400": {
            "$ref": "#/components/responses/400RequestError"
          },
          "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": {
      "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"
        ]
      },
      "TableCell": {
        "type": "object",
        "description": "Defines a single cell in the table, which can appear in either the header or the rows.",
        "properties": {
          "text": {
            "type": "string",
            "description": "Cell text."
          },
          "col_span": {
            "type": "integer",
            "description": "Represents how many columns the cell occupies.",
            "nullable": true
          },
          "row_span": {
            "type": "integer",
            "description": "Represents the number of rows the cell occupies.",
            "nullable": true
          }
        },
        "required": [
          "text"
        ]
      },
      "TableRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the table."
          },
          "data": {
            "type": "object",
            "properties": {
              "sections": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "header": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TableCell"
                      }
                    },
                    "rows": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/TableCell"
                        }
                      }
                    }
                  },
                  "required": [
                    "header",
                    "rows"
                  ]
                }
              }
            },
            "required": [
              "sections"
            ]
          }
        },
        "required": [
          "name",
          "data"
        ]
      },
      "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."
          }
        }
      },
      "UpdateDocumentRecipient": {
        "title": "Recipient",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseActor"
          },
          {
            "$ref": "#/components/schemas/BaseIdentity"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "ZPeAfcpzr9aiVs5vqUf6jg"
              },
              "delivery_methods": {
                "$ref": "#/components/schemas/RecipientDeliveryMethods"
              },
              "redirect": {
                "$ref": "#/components/schemas/RecipientRedirect"
              },
              "type": {
                "type": "string",
                "example": "recipient",
                "enum": [
                  "recipient"
                ]
              }
            }
          }
        ]
      },
      "UpdateDocumentRecipientGroup": {
        "title": "RecipientGroup",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseActor"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "ZPeAfcpzr9aiVs5vqUf6jg"
              },
              "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"
            ]
          }
        ]
      },
      "UpdateDocumentActor": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/UpdateDocumentRecipient"
          },
          {
            "$ref": "#/components/schemas/UpdateDocumentRecipientGroup"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "recipient": "#/components/schemas/UpdateDocumentRecipient",
            "recipient_group": "#/components/schemas/UpdateDocumentRecipientGroup"
          }
        }
      },
      "DocumentUpdateRequestField": {
        "type": "object",
        "description": "Set specific values to the fields. This object maps merge field names to their corresponding values.\n\nEach 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.\n\n**Key Points:**\n- Keys must match the exact merge field names from your template or file.\n- Values must be wrapped in an object with a `value` property.\n- Supported value types: string, number, boolean.\n- Date fields should use RFC 3339 format (e.g., '2019-12-31T00:00:00.000Z').\n- Signature fields cannot be pre-filled.\n\n**Example Usage:**\n- Text field: `\"CustomerName\": {\"value\": \"John Doe\"}`\n- Checkbox: `\"AgreeToTerms\": {\"value\": true}`\n- Date field: `\"DeliveryDate\": {\"value\": \"2019-12-31T00:00:00.000Z\"}`\n",
        "example": {
          "Like": {
            "value": true
          },
          "Delivery": {
            "value": "Same Day Delivery"
          },
          "Date": {
            "value": "2019-12-31T00:00:00.000Z"
          }
        },
        "additionalProperties": {
          "type": "object",
          "properties": {
            "value": {
              "description": "The value to pre-fill the field with. The type of the value depends on the field type in the template.\nFor example, for a checkbox field, you can pass a boolean value, and for a date field, you can pass a date string in RFC 3339 format (e.g., 2019-12-31T00:00:00.000Z).\n",
              "oneOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "required": [
            "value"
          ]
        }
      },
      "DocumentUpdateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the document.",
            "example": "Contract"
          },
          "recipients": {
            "type": "array",
            "description": "The list of recipients you're sending the document to. The ID or email are required. If the ID is passed, an existing recipient will be updated. If the email is passed, a new recipient will be added to CC.",
            "items": {
              "$ref": "#/components/schemas/UpdateDocumentActor"
            }
          },
          "fields": {
            "$ref": "#/components/schemas/DocumentUpdateRequestField"
          },
          "tokens": {
            "type": "array",
            "description": "Create or initialize multiple variables with their values using tokens/values list.",
            "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": [
              "updated_via_api",
              "test_document"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "You can pass arbitrary data in the key-value format to associate custom information with a document. This information is returned in any API requests for the document details by id. If metadata exists in a document then the value will be updated. Otherwise, metadata will be added to the document.",
            "example": {
              "my_favorite_pet": "Cat"
            }
          },
          "pricing_tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PricingTableRequest"
            }
          },
          "tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TableRequest"
            }
          },
          "images": {
            "type": "array",
            "description": "You can pass a list of images to image blocks (one image in one block) for replacement.",
            "items": {
              "type": "object",
              "properties": {
                "urls": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "https://s3.amazonaws.com/pd-static-content/public-docs/pandadoc-panda-bear.png"
                  ]
                },
                "name": {
                  "type": "string",
                  "example": "Image 1"
                }
              },
              "required": [
                "urls",
                "name"
              ]
            }
          },
          "texts": {
            "type": "array",
            "description": "You can pass a list of texts to text blocks for replacement.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The name of the text block to update.",
                  "example": "Legal Terms Section"
                },
                "data": {
                  "type": "string",
                  "description": "The rich text content to be inserted into the block. Supports markdown.",
                  "example": "## Terms of Service\nThis document outlines the terms and conditions. \n- **Acceptance:** By using our service, you agree to these terms.\n- **Changes:** We may update these terms at any time.\n"
                }
              },
              "required": [
                "name",
                "data"
              ]
            }
          }
        }
      }
    },
    "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."
                }
              }
            }
          }
        }
      },
      "400RequestError": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "type": {
                  "type": "string",
                  "example": "request_error"
                },
                "detail": {
                  "type": "object",
                  "example": {
                    "count": [
                      "A valid integer is required."
                    ],
                    "order_by": [
                      "value is not a valid choice."
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```