---
title: "Revise Document"
method: POST
path: "/api/v1/documents/{document_id}/revise"
tags: ["v1", "documents"]
---

# Revise Document

`POST /api/v1/documents/{document_id}/revise`

## Request

- Base URL: `https://zsign.io` (the document declares no server; this is the origin it was published from)
- URL: `https://zsign.io/api/v1/documents/{document_id}/revise`
- Auth: HTTP bearer

Copy a changes-requested envelope into a new unsent Draft.

The draft keeps the source's documents, fields, recipients and public
metadata, with `metadata.revision_of` set to the source id. Edit it with
the /api/v1/documents/drafts routes, then send it with
POST /api/v1/documents/drafts/{document_id}/send; `revision_of` is
carried on send, so the first qualifying revision is free while the
promotion is enabled. No credit is charged here.

404 when the document is missing or belongs to another org. 409
`not_changes_requested` unless the newest session was declined with a
change request. API-key twin of the dashboard
POST /api/documents/{document_id}/revise.

## Path parameters

- `document_id` string, uuid, required

## Response `201`

Successful Response

- AgentDraftResponse: Unsent draft created or updated by an agent. Not a send receipt: no session_id, no signing_urls, credits_charged is always 0.
  - `document_id` string, uuid, required
  - `status` 'draft' | 'ready_to_send', required
  - `name` string, required
  - `filename` string, required
  - `parsed_fields` object[], required
  - `parties` string[], required
  - `recipients` RecipientData[], required
    - `email` string, email, required
    - `name` string, required
    - `role` string, required
    - `signing_order` integer, nullable
  - `metadata` object, nullable
  - `credits_charged` integer
  - `sent` boolean
  - `documents` EnvelopeDocumentOut[]
    - `id` string, required
    - `name` string, required
    - `filename` string, required
    - `page_start` integer, required
    - `page_count` integer, required
    - `position` integer, required
  - `revision` integer
  - `package_file_count` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zsign/apis/zsign-api.md) · [All operations](https://skmtc.dev/zsign/apis/zsign-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zsign/apis/zsign-api/revisions/a674ac4137ba?raw)