---
title: "Create an envelope (quote)"
method: POST
path: "/v1/envelopes"
tags: ["sign"]
---

# Create an envelope (quote)

`POST /v1/envelopes`

## Request

- Base URL: `https://api.noerrands.com/c/sign`
- URL: `https://api.noerrands.com/c/sign/v1/envelopes`
- Auth: HTTP bearer

Upload a PDF (document_url or document_base64, max 10 MB, 100 pages) with a title and 1 to 5 signers (name + email), or self_sign with signer_name for the human to sign it themselves, and optional fields placed by page and x/y fractions (omit fields to append a signature page); stores a DRAFT and returns a price quote (quote.total_cents) whose quote_id send_envelope takes -- free, sends nothing and charges nothing. Not available for wills, codicils or testamentary trusts; adoption, divorce or other family-law matters; court orders or court documents; utility shut-off, eviction, foreclosure, repossession or insurance-cancellation notices; product-recall notices; hazardous-materials papers; negotiable instruments; or anything that must be notarized or witnessed.

## Request body

- object
  - `title` string, required: What the document is, shown to every signer, e.g. "Lease for 12 Oak St".
  - `document_url` string, uri: HTTPS URL of the PDF. Exactly one of document_url or document_base64. At most 10 MB and 100 pages, not password-protected.
  - `document_base64` string: The PDF itself, base64 (a data:application/pdf;base64, prefix is fine). Exactly one of document_url or document_base64.
  - `self_sign` boolean: True when the human is signing this themselves (for example a form you filled in). Give signer_name, not signers.
  - `signer_name` string: self_sign only: the human's full name. Required there.
  - `signer_email` string, email: self_sign only: the human's email for the certificate. Defaults to the account email.
  - `signers` object[]: 1 to 5 people who must sign, in order of position. Omit for self_sign.
    - `name` string, required: The signer's full name, as it should appear on the certificate.
    - `email` string, email, required: The email address the human will send this signer's link to. We do not email it.
    - `order` integer: Optional signing order. Lower signs first, equal orders sign in parallel. Omit on every signer for everyone at once.
  - `fields` object[]: Optional, up to 100. Where each signer signs, as page + x/y fractions from the top-left. Omit to append a signature page with one block per signer instead. With fields, every signer needs at least one signature field.
    - `type` 'signature' | 'initials' | 'date' | 'text', required: signature and initials take the signer's signature; date is filled with the signing date; text asks the signer to type a value (label says what).
    - `signer` integer: Which signer fills this field: their 1-based position in signers. Default 1.
    - `page` integer, required: 1-based page number.
    - `x` number, required: Left edge of the box as a fraction of the page width, from the left (0..1).
    - `y` number, required: Top edge of the box as a fraction of the page height, from the TOP (0..1).
    - `width` number: Box width as a fraction of the page width. Defaults by type.
    - `height` number: Box height as a fraction of the page height. Defaults by type.
    - `label` string: Text fields: what to ask the signer for, e.g. "Job title".
    - `required` boolean: Text fields only. Default true.
  - `message` string: Optional note shown to signers above the document.
  - `expires_in_days` integer: Days the signing links stay open after sending. Default 30.
  - `retention_days` 30 | 90 | 365 | 1095: Days we keep the finished document after completion before deleting it: 30, 90, 365 (default) or 1095. The human can delete it any time sooner.

## Response `200`

Success.

- object
  - `envelope_id` string, required
  - `status` 'draft', required
  - `title` string, required
  - `mode` 'request' | 'self', required
  - `pages` integer, required
  - `placement` 'fields' | 'signature_page', required
  - `document_sha256` string, required
  - `signers` object[], required
    - `signer_id` string, required
    - `name` string, required
    - `email` string, required
    - `order` integer, required
  - `quote` object, required
    - `quote_id` string, required: Pass to send_envelope to accept this price.
    - `total_cents` integer, required: Exactly what send_envelope will charge.
    - `breakdown` object[], required
      - `item` string, required
      - `cents` integer, required
    - `expires_at` string, date-time, required
    - `free_self_sign` boolean, required: True when this is the account's free self-sign.
  - `expires_in_days` integer, required
  - `retention_days` integer, required

## Other responses

- `400`: invalid_request
- `401`: unauthorized. Carries WWW-Authenticate: Bearer resource_metadata="..."
- `403`: forbidden_scope: a write tool called with a read-only key.
- `404`: not_found
- `429`: rate_limited
- `502`: provider_error

---

[API](https://skmtc.dev/noerrands/apis/no-errands-sign-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-sign-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-sign-api/revisions/df9080c22e41?raw)