---
title: "Prepare a document for signature"
method: POST
path: "/documents/{document_id}/envelopes"
tags: ["envelope"]
---

# Prepare a document for signature

`POST /documents/{document_id}/envelopes`

## Request

- Base URL: `https://localhost:4410/api/v1`
- URL: `https://localhost:4410/api/v1/documents/{document_id}/envelopes`
- Auth: HTTP bearer

Use this to send a document for signature. Makes a draft envelope: the document's current version, the people who sign it and their signature fields. i_sign adds the person you work for as the last signer, after the others. Nothing is sent until the person taps Send on the card that shows it.

## Path parameters

- `document_id` string, required: From document_list or document_add.

## Request body

- object
  - `signers` object[]
    - `name` string, required: Their full name as it should read under the signature. Ask if you don't know it.
    - `email` string, email, required
    - `auth` 'link' | 'code': code also emails them a six-digit code to open it.
    - `order` integer: Signing order; the same number signs at the same time.
    - `intent` 'sign' | 'acknowledge': acknowledge: they confirm they received it, rather than sign it.
  - `i_sign` boolean: The person you work for signs too, last.
  - `message` string: A note in the signing email, in the person's words.
  - `fields` 'detect' | 'signature_page': detect finds the signature lines; signature_page adds a page of blocks instead.
  - `accept_proposed_fields` boolean: Keep the found fields that name their signer; drop the rest.
  - `template_id` string: One of the document's templates from document_list. Signers fill its roles in order; it sets the fields.

## Response `200`

The result.

- object
  - `id` string, required
  - `document_id` string, required
  - `version_id` string, required
  - `title` string, required
  - `message` string, nullable, required
  - `status` 'draft' | 'sent' | 'completed' | 'declined' | 'voided' | 'expired', required
  - `ordered` boolean, required
  - `pages` integer, required
  - `signature_page` boolean, required
  - `signers` object[], required
    - `id` string, required
    - `name` string, required
    - `email` string, required
    - `position` integer, required
    - `order` integer, required
    - `status` 'waiting' | 'notified' | 'viewed' | 'signed' | 'declined' | 'change_requested', required
    - `is_me` boolean, required
    - `auth` 'link' | 'code', required
    - `intent` 'sign' | 'acknowledge', required
    - `viewed_at` string, date-time, nullable, required
    - `signed_at` string, date-time, nullable, required
    - `declined_at` string, date-time, nullable, required
    - `decline_reason` string, nullable, required
    - `change_request` object, nullable, required
      - `reason` 'wrong_entity' | 'wrong_signatory' | 'wrong_terms' | 'other', required
      - `at` string, date-time, required
      - `closed_at` string, date-time, nullable, required
      - `reply` string, nullable, required
      - `untrusted_content` object, required
        - `note` string, nullable, required
        - `signatory` object, nullable, required
          - `name` string, required
          - `email` string, required
          - `title` string, nullable, required
    - `same_origin_as` object[], required
      - `name` string, required
      - `by` 'ip_address' | 'browser_within_a_minute', required
    - `replaced` object[], required
      - `name` string, required
      - `email` string, required
      - `reason` string, required
      - `at` string, date-time, required
  - `fields` object[], required
    - `id` string, required
    - `signer_id` string, nullable, required
    - `kind` 'signature' | 'initials' | 'date' | 'name' | 'text', required
    - `page` integer, required
    - `x` number, required
    - `y` number, required
    - `width` number, required
    - `height` number, required
    - `required` boolean, required
    - `filled` boolean, required
    - `proposed` boolean, required
    - `source` 'tag' | 'form' | 'signature_line' | 'template', nullable, required
    - `group` string, nullable, required
    - `match` 'tag' | 'name' | 'company' | 'email_domain' | 'decision', nullable, required
    - `decision` object, nullable, required
      - `model` string, required
      - `probability` number, required
      - `id` string, nullable, required
  - `url` string, required
  - `code` string, nullable, required
  - `disputed` object, nullable, required
    - `by` string, required
    - `at` string, date-time, required
    - `note` string, nullable, required
    - `resolved_at` string, date-time, nullable, required
    - `resolution` string, nullable, required
  - `result_sha256` string, nullable, required
  - `created_at` string, date-time, required
  - `sent_at` string, date-time, nullable, required
  - `completed_at` string, date-time, nullable, required
  - `voided_at` string, date-time, nullable, required
  - `expires_at` string, date-time, nullable, required
  - `reminded_at` string, date-time, nullable, required
  - `reminders` object, required
    - `every_days` integer, nullable, required
    - `next_at` string, date-time, nullable, required
  - `needs_review` boolean, required
  - `exclusion_override` string, nullable, required
  - `hold` 'funding', nullable, required
  - `safe` object, nullable, required
    - `id` string, required
    - `investor` string, required
    - `amount` string, required

## Other responses

- `default`: An RFC 9457 problem.

---

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