---
title: "Update document"
method: PATCH
path: "/v1/documents/{id}"
tags: ["Documents"]
---

# Update document

`PATCH /v1/documents/{id}`

## Request

- Base URL: `https://api.signvoy.com`
- URL: `https://api.signvoy.com/v1/documents/{id}`
- Auth: one of:
  - API key in header `X-Workspace-Id`
  - HTTP bearer
  - HTTP bearer

Updates document details (only allowed in draft state)

## Path parameters

- `id` string, uuid, required

## Request body

- UpdateDocumentDto
  - `name` string: Custom name for the document
  - `message` string: Message to include with the signing request
  - `emailSubject` string: Replaces the generated subject line on the signing request, the awaiting-your-turn heads-up, and reminders (which stay prefixed with "Reminder: "). Completion, decline, void and expiry notices always use their standard wording. Leave unset for the generated subject.
  - `routingMode` 'parallel' | 'sequential': Signing-order mode. parallel (default): all recipients are invited at once. sequential: recipients are activated group-by-group by ascending order value — the next group is only activated once the current group has fully signed.
  - `reminders` ReminderSettingsDto
    - `enabled` boolean: Whether automatic reminders are enabled for this document
    - `intervalDays` number: Days between automatic reminder emails
    - `maxReminders` number: Maximum number of automatic reminders before giving up
  - `expiry` ExpirySettingsDto
    - `days` number: Days after sending that this document can still be signed. The absolute deadline is derived from this when the document is sent.
  - `recipients` CreateDocumentRecipientDto[]: Everyone involved with the document, in signing order — those who sign, those who must view and confirm, and those who just receive a copy. At least one must sign or view.
    - `roleKey` string, required: Template role key this recipient fills (matches `version.content.recipients[].key`). Required for `signer`; ignored for `cc` and `viewer`, which hold no fields and are assigned a synthetic key.
    - `name` string, required: Recipient's full name
    - `email` string: Recipient's email address for notifications
    - `type` 'signer' | 'cc' | 'viewer': What this recipient is asked to do. `signer` (default) fills in fields and signs. `cc` receives a copy and never holds up the signing order. `viewer` must open and confirm they reviewed the document, and blocks the order until they do.
    - `order` number: Position in the signing order. Signers default to the order set on their template role. For a `cc` this is also *when* the copy is sent: a position after every signer gets the certified final document, while a mid-order position gets the document as it stands at that step.

## Response `200`

- DocumentDto
  - `id` string, uuid, required
  - `workspaceId` string, uuid, required
  - `templateId` string, uuid, required
  - `templateVersionId` string, uuid, required
  - `ownerId` string, required: Clerk user ID of the document owner
  - `name` string, required: Human-readable document name
  - `status` 'draft' | 'sent' | 'in_progress' | 'completed' | 'declined' | 'voided' | 'expired', required: Current document lifecycle state
  - `routingMode` 'parallel' | 'sequential', required: Signing-order mode
  - `message` string: Custom message sent with the signing request
  - `emailSubject` string: Sender's replacement subject for the signing request and reminders. Absent means the generated subject is used.
  - `createdAt` integer, required: Creation timestamp (Unix ms)
  - `sentAt` integer: Unix ms when sent
  - `completedAt` integer: Unix ms when all signed
  - `voidedAt` integer: Unix ms when voided
  - `expiresAt` integer: Unix ms when expires/expired
  - `documentHash` string: SHA-256 fingerprint of the certified final PDF
  - `certifiedAt` integer: Unix ms when certified
  - `reminderEnabled` boolean, required: Whether automatic reminders are enabled
  - `reminderIntervalDays` integer, required: Days between automatic reminders
  - `reminderMaxCount` integer, required: Max automatic reminders
  - `reminderCount` integer, required: Automatic reminders sent so far
  - `lastReminderAt` integer: Unix ms of the most recent reminder (auto or manual)
  - `recipients` DocumentRecipientDto[], required
    - `id` string, uuid, required
    - `roleKey` string, required: Matches template version recipient key
    - `roleName` string, required: Role display name snapshot at send time
    - `type` 'signer' | 'cc' | 'viewer', required: What this recipient is asked to do. `signer` fills in fields and signs. `cc` receives a copy and never holds up the signing order. `viewer` must open and confirm they reviewed the document.
    - `name` string, required
    - `email` string: Recipient email address
    - `color` string, required: Hex colour assigned to this recipient
    - `order` integer, required: Signing order (0-based)
    - `status` 'pending' | 'signed' | 'acknowledged' | 'copy_sent' | 'declined', required: Each role reaches its own terminal status: a signer `signed`, a viewer `acknowledged`, a CC `copy_sent`. They are never interchangeable.
    - `signedAt` integer: Unix ms timestamp when recipient signed
    - `declinedAt` integer: Unix ms timestamp when recipient declined
    - `declineReason` string: Reason for declining
    - `signUrl` string: URL where this recipient can complete signing
    - `lastRemindedAt` integer: Unix ms timestamp when recipient was last reminded (manual or automatic)
    - `hasActiveSigningLink` boolean: Whether this recipient has an active signing link (can currently sign)
  - `sendBlockers` object[], required: Reasons a draft cannot yet be sent. Empty array when the document is ready to send or is not in draft state.
    - `code` 'NO_RECIPIENTS' | 'RECIPIENT_EMAIL_MISSING' | 'CC_EMAIL_MISSING', required
    - `message` string, required
    - `recipientIds` string[]

## Other responses

- `400`: Invalid input or document not in draft state
- `403`: Forbidden - Not the document owner
- `404`: Document not found

---

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