---
title: "Create an envelope (inline or from a template)"
method: POST
path: "/api/v1/envelopes"
tags: ["Envelopes"]
---

# Create an envelope (inline or from a template)

`POST /api/v1/envelopes`

## Request

- Base URL: `https://swiftsign.ca`
- URL: `https://swiftsign.ca/api/v1/envelopes`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string: Optional. Replays the original response for a duplicate request body.

## Request body

- union
  - InlineEnvelopeBody: Create an envelope from inline base64 documents, recipients, and fields.
    - `subject` string, required
    - `message` string
    - `documents` DocumentInput[], required
      - `name` string, required
      - `base64` string, required: Base64-encoded PDF bytes.
    - `recipients` RecipientInput[], required
      - `name` string, required
      - `email` string, email, required
      - `role` 'SIGNER' | 'CC'
      - `routingOrder` integer: Signing order; lower routes first.
    - `fields` FieldInput[]
      - `recipientIndex` integer, required: Index into the recipients[] array.
      - `document` integer, required: Index into the documents[] array.
      - `type` 'SIGNATURE' | 'NAME' | 'DATE' | 'TEXT' | 'INITIALS' | 'CHECKBOX' | 'RADIO' | 'DROPDOWN' | 'ATTACHMENT', required: Signature/data field type to place on a document.
      - `page` integer: 1-indexed page. Ignored when anchor resolves.
      - `x` number: X as a percent (0–100) of page width, top-left origin.
      - `y` number: Y as a percent (0–100) of page height, top-left origin.
      - `width` number
      - `height` number
      - `anchor` string: Anchor text to place the field next to.
      - `yOffset` number: Vertical nudge (percent) applied to an anchor match.
      - `options` string[]: Choices for RADIO / DROPDOWN fields.
  - TemplateEnvelopeBody: Create an envelope from a saved template by assigning each role.
    - `templateId` string, required
    - `roleAssignments` object, required: Map of template roleName → { name, email }.
    - `subject` string
    - `message` string

## Response `201`

Envelope created (DRAFT). Call POST /api/v1/envelopes/{id} with action:"send".

- Envelope
  - `id` string, required
  - `subject` string, required
  - `message` string, nullable, required
  - `status` 'DRAFT' | 'SENT' | 'COMPLETED' | 'DECLINED' | 'VOIDED', required
  - `livemode` boolean, required
  - `createdAt` string, required
  - `documents` Document[], required
    - `id` string, required
    - `name` string, required
    - `pageCount` integer, required
    - `order` integer, required
  - `recipients` Recipient[], required
    - `id` string, required
    - `name` string, required
    - `email` string, email, required
    - `role` 'SIGNER' | 'CC', required
    - `routingOrder` integer, required
    - `status` string, required

## Other responses

- `400`: Validation error.
- `401`: Missing or invalid API key.
- `402`: Monthly envelope quota exceeded.
- `403`: API key lacks the envelopes:write scope.
- `422`: One or more field anchors could not be resolved.
- `429`: Rate limited.

---

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