---
title: "Replace Draft Fields"
method: PUT
path: "/api/v1/documents/drafts/{document_id}/fields"
tags: ["v1", "documents"]
---

# Replace Draft Fields

`PUT /api/v1/documents/drafts/{document_id}/fields`

## 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/drafts/{document_id}/fields`
- Auth: HTTP bearer

## Path parameters

- `document_id` string, uuid, required

## Request body

- DraftFieldsRequest: Body of PUT /api/documents/drafts/{id}/fields -- a whole-list replace, not per-field CRUD (see DraftDocumentService.replace_fields).
  - `fields` DraftField[], required
    - `type` 'signature' | 'initials' | 'text' | 'date' | 'checkbox' | 'radio', required
    - `party` string, nullable
    - `semantic_type` 'full_name', nullable
    - `label` string, nullable
    - `name` string, nullable
    - `required` boolean
    - `position` FieldPosition, required: Position data for a field on the PDF
      - `page_number` integer, required: Page number (1-indexed)
      - `file_position` integer: 1-based source PDF index in the envelope package. At most MAX_ENVELOPE_DOCUMENTS.
      - `x` number, required: X coordinate (top-left origin)
      - `y` number, required: Y coordinate (top-left origin)
      - `width` number, required: Field width
      - `height` number, required: Field height
    - `document_id` string, nullable
    - `group` string, nullable
    - `option_value` string, nullable
    - `default_value` string, nullable
    - `locked` boolean
  - `intended_recipients` IntendedRecipientIn[], nullable
    - `role` string, required
    - `name` string
    - `email` string
  - `revision` integer, nullable

## Response `200`

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)