---
title: "Send Document For Signing"
method: POST
path: "/api/v1/documents/send"
tags: ["v1", "documents"]
---

# Send Document For Signing

`POST /api/v1/documents/send`

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

Upload a PDF and send it for signing immediately — or leave it as a
Draft for human review.

- **file**: one PDF. Keep this for existing callers. Combined with
  `files` when both are sent; order is `file` first, then `files`.
- **files**: repeating extra PDF parts. Accepted together with `file`.
  Cap is `MAX_ENVELOPE_DOCUMENTS` (default 10) and
  `MAX_COMBINED_BYTES` from `MAX_PDF_SIZE_MB`.
- **document_names**: optional JSON array of display names aligned to
  `file` first, then `files`.
- **recipients**: JSON array of recipient objects with name, email, and role.
  Required when sending; optional when `draft=true` / `auto_send=false`.
- **name**: Optional document name
- **sequential**: Optional boolean (multipart string). Default true:
  recipients sign one at a time in list order. Set false so everyone
  can sign at once. This is the sequential send-body flag.
- **metadata**: Optional JSON object of opaque integrator context, echoed
  into `data.metadata` on every webhook for this envelope. Flat
  string->string only. Use it to carry your own join key -- `document_id`
  is NOT stable for this purpose, because `document.completed` reports the
  id of the COMPLETED document, not the original.
  Example: `{"deal_id": "d_123", "stage": "contract_out"}`
- **auto_send**: default `true`. Set `false` to create a Draft (no credit
  debit, no invites). Existing callers that omit this still send.
- **draft**: `true` is the same as `auto_send=false` and wins if both
  are set, so draft mode cannot accidentally send.
- **fields**: optional JSON array of placed fields (same shape as
  PUT /api/v1/documents/drafts/{id}/fields). Used only in draft mode.
- **prefill**: optional JSON object of per-send text values keyed by
  field `"party:name"`, e.g. `{"client:company": "Acme Inc"}`. Sets or
  overrides that text field's `default_value` for this send only.
  Unknown or non-text keys are a 422 `invalid_prefill_key`. Not
  accepted in draft mode: set `fields[].default_value` instead.
- **Idempotency-Key** header: optional. When set on a send (not draft),
  the server claims (org, `v1.documents.send`, key) before the credit
  debit. A retry with the same key and byte-identical inputs replays
  the stored response; the same key with different inputs is a 409; a
  concurrent in-flight request with the same key is a 409 with
  Retry-After. A send interrupted mid-flight becomes retakable after
  ten minutes.

Example recipients:
```json
[
    {"name": "John Doe", "email": "john@example.com", "role": "employee"},
    {"name": "Jane Smith", "email": "jane@example.com", "role": "manager"}
]
```

Rate limit: 100 requests per hour per API key

## Headers

- `Idempotency-Key` string, nullable

## Response `201`

Successful Response

- union
  - DocumentSendResponse
    - `document_id` string, uuid, required
    - `session_id` string, uuid, required
    - `signing_urls` SigningURL[], required
      - `recipient_email` string, required
      - `recipient_name` string, required
      - `signing_url` string, required
      - `token` string, required
    - `parsed_fields` object[], required
    - `filename` string, nullable
    - `documents` PackageFileInfo[]
      - `index` integer, required
      - `filename` string, required
      - `pages` integer, required
      - `sha256` string, required
      - `size` integer, required
    - `package_file_count` integer
  - 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)