---
title: "Create Draft"
method: POST
path: "/api/v1/documents/drafts"
tags: ["v1", "documents"]
---

# Create Draft

`POST /api/v1/documents/drafts`

## 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`
- Auth: HTTP bearer

Upload one or more PDFs as a Draft, or stamp a saved template.

`files` (repeatable) creates a multi-document envelope; `file` is the
single-document form and is still accepted; when both are given the
order is `file` first, then `files`. `document_names` is an optional
JSON array of display names aligned with that order. Exactly one of
`file`/`files` or `template_id`. `role_mapping` (template only) is a
JSON object {source_role: destination_role}; unmapped roles stay
literal.

Tags are detected best-effort (an untagged PDF is a valid starting
point). Pass `fields` to place them now, or leave them for a human in
the dashboard editor. Recipients are stored for later send / Approve.

## 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)