---
title: "Prepare Document"
method: POST
path: "/api/v1/documents/prepare"
tags: ["v1", "documents"]
---

# Prepare Document

`POST /api/v1/documents/prepare`

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

Infer signing fields and return either a preview or the tagged PDF.

`document_base64` is the PDF (max 10MB). `signers` is an optional hint
list (`name`, `email`, `role`, `order`). Until the calling user has
approved a preview, every call returns `status: preview` with
`prepare_id` and no PDF. After that, a call returns `status: ready`
and `pdf_base64` when confidence is at least 0.85, and a preview
otherwise. `prepare_id` plus
`approve: true` returns the stored PDF. No envelope is created and no
credit is charged.

Rate limit: 100 requests per hour per API key.

## Request body

- PrepareRequest
  - `document_base64` string, nullable
  - `signers` SignerHint[], nullable
    - `name` string, nullable
    - `email` string, nullable
    - `role` string, nullable
    - `order` integer, nullable
  - `prepare_id` string, uuid, nullable
  - `approve` boolean

## Response `200`

Successful Response

- PrepareResponse
  - `status` string, required
  - `confidence` number, required
  - `reasons` string[]
  - `fields` PrepareFieldOut[]
    - `type` string, required
    - `party` string, required
    - `name` string, required
    - `page` integer, required
    - `bbox` number[], required
  - `role_map` PrepareRoleOut[]
    - `party` string, required
    - `name` string, nullable
    - `email` string, nullable
    - `role` string, required
  - `prepare_id` string, nullable
  - `pdf_base64` string, nullable

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