---
title: "Create an envelope"
method: POST
path: "/api/v1/envelopes"
tags: ["envelopes"]
---

# Create an envelope

`POST /api/v1/envelopes`

Creates a draft envelope with its participant and field graph. The document arrives by public URL, inline base64 content, chat-authored text rendered to PDF, a same-organization envelope document, or deferred upload (`{ upload: true }` returns a short-lived signed `uploadUrl`; it is never re-issued after create). Returns immediately with the envelope, a review URL for the web review page, a human/agent-readable `note` describing the next step, and never blocks on field detection. URL and inline documents enqueue field detection asynchronously after the document is stored (the envelope moves draft → detecting → review); deferred-upload envelopes skip detection and remain sendable with manually placed fields. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422. A replayed create re-mints the review URL but never the one-shot upload URL.

## Request body

- object
  - `document` union, required
    - object
      - `url` string, uri, required
      - `filename` string
    - object
      - `contentBase64` string, required
      - `filename` string, required
    - object
      - `text` string, required
      - `filename` string
    - object
      - `envelopeId` string, uuid, required
    - object
      - `upload` true, required
      - `filename` string, required
  - `participants` object[], required
    - `name` string, required
    - `email` string, email, required
    - `company` string, nullable
    - `title` string, nullable
    - `detectedPartyIndex` integer, nullable
  - `fields` object[], required
    - `participantIndex` integer
    - `partyIndex` integer
    - `type` 'signature' | 'initials' | 'date' | 'text' | 'checkbox', required
    - `page` integer, required
    - `x` number, required
    - `y` number, required
    - `width` number, required
    - `height` number, required
    - `label` string, nullable
    - `required` boolean
    - `prefillValue` string, nullable — Static sender-supplied value for text or date fields. Ignored on checkbox fields, which always remain signer-controlled.
    - `autoSource` 'signed_date' | 'participant_name' | 'participant_email' | 'participant_company' | 'participant_title' | 'sender_org_name' | 'null', nullable — Derive this field's value server-side when the signer signs: signed_date (date fields) or participant_name / participant_email / participant_company / participant_title / sender_org_name (text fields). Mutually exclusive with prefillValue. The resolved value is recorded in the envelope's audit trail.
    - `proposedAutoSource` 'signed_date' | 'participant_name' | 'participant_email' | 'participant_company' | 'participant_title' | 'sender_org_name' | 'null', nullable — Detection-proposal echo. On draft updates, echo the proposedAutoSource you read to keep the suggestion; omitting or nulling it dismisses it. Cannot introduce or change a proposal (detection is the only origin); ignored at envelope create.
    - `source` 'detected' | 'manual' | 'template'
  - `displayName` string
  - `policy` object
    - `deliveryMode` 'review_first' | 'auto_send'
    - `legalFramework` string, nullable
    - `consumerDisclosure` boolean
    - `expiresAt` string, date-time
    - `reminderPolicy` unknown
  - `metadata` unknown

## Response `201`

Envelope created (status draft, version 1)

- object
  - `envelope` object, required
    - `envelope` object, required
      - `id` string, required
      - `organizationId` string, required
      - `teamId` string, nullable, required
      - `templateId` string, nullable, required
      - `templateContentHash` string, nullable, required
      - `status` 'draft' | 'detecting' | 'review' | 'in_progress' | 'completed' | 'declined' | 'voided' | 'expired', required
      - `detectionStatus` 'none' | 'running' | 'succeeded' | 'failed', required
      - `version` integer, required
      - `originalFilename` string, nullable, required
      - `displayName` string, nullable, required
      - `sourceFormat` string, nullable, required
      - `contentHash` string, nullable, required
      - `sizeBytes` number, nullable, required
      - `deliveryMode` string, required
      - `legalFramework` string, nullable, required
      - `consumerDisclosure` boolean, required
      - `expiresAt` string, date-time, nullable, required
      - `scheduledSendAt` string, date-time, nullable, required
      - `reminderPolicy` unknown
      - `sentAt` string, date-time, nullable, required
      - `completedAt` string, date-time, nullable, required
      - `declinedAt` string, date-time, nullable, required
      - `voidedAt` string, date-time, nullable, required
      - `expiredAt` string, date-time, nullable, required
      - `metadata` unknown
      - `senderUserId` string, nullable
      - `senderName` string, nullable
      - `senderEmail` string, nullable
      - `detectedParties` unknown
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `participants` object[], required
      - `id` string, required
      - `envelopeId` string, required
      - `organizationId` string, required
      - `orderIndex` integer, required
      - `name` string, required
      - `email` string, required
      - `company` string, nullable
      - `title` string, nullable
      - `status` 'pending' | 'signed' | 'declined', required
      - `detectedPartyIndex` integer, nullable
      - `consentedAt` string, date-time, nullable, required
      - `signedAt` string, date-time, nullable, required
      - `declinedAt` string, date-time, nullable, required
      - `declineReason` string, nullable, required
      - `lastViewedAt` string, date-time, nullable, required
      - `lastIpAddress` string, nullable, required
      - `lastUserAgent` string, nullable, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `fields` object[], required
      - `id` string, required
      - `envelopeId` string, required
      - `organizationId` string, required
      - `participantId` string, nullable, required
      - `partyIndex` integer, nullable
      - `type` 'signature' | 'initials' | 'date' | 'text' | 'checkbox', required
      - `page` integer, required
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
      - `label` string, nullable, required
      - `required` boolean, required
      - `source` 'detected' | 'manual' | 'template', required
      - `prefillValue` string, nullable, required
      - `autoSource` 'signed_date' | 'participant_name' | 'participant_email' | 'participant_company' | 'participant_title' | 'sender_org_name' | 'null', nullable, required
      - `proposedAutoSource` 'signed_date' | 'participant_name' | 'participant_email' | 'participant_company' | 'participant_title' | 'sender_org_name' | 'null', nullable, required
      - `value` string, nullable, required
      - `filledAt` string, date-time, nullable, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
  - `reviewUrl` string, uri, required
  - `uploadUrl` string, uri
  - `note` string, required

## Other responses

- `401` — Missing or invalid API key
- `413` — Raw request body exceeds the pre-parse size limit
- `422` — Validation failed: malformed input, document intake rejected (private address, size cap, content type), or duplicate participant emails
- `502` — Document storage failed; the draft exists without a stored document

---

[API](https://skmtc.net/atlaswork/apis/atlas-api.md) · [All operations](https://skmtc.net/atlaswork/apis/atlas-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlaswork/atlas-api/versions/a8a1e7479c90/schema)