---
title: "Create an envelope from a template"
method: POST
path: "/api/v1/templates/{id}/envelopes"
tags: ["Templates"]
---

# Create an envelope from a template

`POST /api/v1/templates/{id}/envelopes`

Requires a recipient for every template role. By default auto-sends because the layout was reviewed at save time; pass autoSend: false for a review-first draft. Supports the optional Idempotency-Key header. Repeating the same key and request replays the original 201 response; a key currently in flight returns 409, and reusing a key with a different request returns 422.

## Path parameters

- `id` string, required — Template id

## Request body

- object
  - `recipients` object, required
  - `prefill` object
  - `displayName` string
  - `autoSend` boolean

## Response `201`

Instantiated envelope

- union
  - object
    - `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
  - 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
    - `note` string
    - `prefillUnmatched` string[]

## Other responses

- `401` — Missing or invalid API key
- `402` — Insufficient send credits
- `404` — Template not found in this organization
- `409` — An idempotent request with this key is already in flight
- `422` — Recipients or prefill values are invalid
- `502` — Document storage copy failed

---

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