# Create a Template and Send an Envelope from it

Templates let you define a reusable signing workflow — document, stages, recipients, and field placement — and then spin up envelopes from it on demand. This guide walks through the full template setup and shows you how to create an envelope from it.

## Prerequisites

- A valid **JWT Bearer token** or **Personal Access Token**
- Your **organization ID** (`organizationId`)
- A document ready to upload


## Part 1 — Build the Template

### Step 1 — Create a Template

Create the template container. Give it a name so you can identify it later. Additionally set optionally the expiration.

```http
POST /api/v1/organizations/{organizationId}/templates
```

```json
{
  "name": "Standard Lease Agreement",
  "expiration": {
    "expiresAt": "2026-04-25T09:16:24.350Z",
    "mode": "absolute"
  }
}
```

**Response `201 Created`**

```json
{
  "id": "f7e6d5c4-1234-1234-1234-ba9876543210"
}
```

Save the returned `id` — this is your `templateId` for every subsequent call in this section.

### Step 2 — Upload a Document to the Template

Attach the PDF that signers will receive. This endpoint uses `multipart/form-data`, not JSON.

```http
POST /api/v1/organizations/{organizationId}/templates/{templateId}/files
Content-Type: multipart/form-data
```

| Field | Type | Description |
|  --- | --- | --- |
| `file` | binary | The PDF file to attach |


**Response `201 Created`**

```json
{
  "id": "9c8b7a69-1234-1234-1234-987654321000"
}
```

Save the returned `id` — this is your `fileId`, used when placing signature fields.

### Step 3 — Add a Signing Stage to the Template

A stage represents one step in the workflow. Recipients in the same stage sign in parallel; stages execute in order.

```http
POST /api/v1/organizations/{organizationId}/templates/{templateId}/stages
```

```json
{
  "name": "First",
  "requiredRecipientCompletions": 1,
  "type": "signer"
}
```

**Response `201 Created`**

```json
{
  "id": "b2a1f0e9-1234-1234-1234-726150403020"
}
```

Save the returned `id` — this is your `stageId`.

### Step 4 — Add a Recipient to the Stage

Add a recipient to the stage. In a template the recipient typically represents a role — actual contact details can be overridden when you create an envelope from the template.

```http
POST /api/v1/organizations/{organizationId}/templates/{templateId}/stages/{stageId}/recipients
```

```json
{
  "givenName": "John",
  "surname": "Doe",
  "email": "john.doe@sample.com",
  "notificationChannels": [
    "email"
  ]
}
```

**Response `201 Created`**

```json
{
  "id": "1a2b3c4d-1234-1234-1234-ef0123456789"
}
```

Save the returned `id` — this is your `recipientId`, used when placing the signature field.

### Step 5 — Place a Signature Field

Define where the signature should appear and assign it to the recipient. This call fully replaces all field tasks for the file, so send the complete list each time.

```http
PUT /api/v1/organizations/{organizationId}/templates/{templateId}/files/{fileId}/tasks
```

```json
{
  "tasks": [
    {
      "field": {
        "fieldType": "Signature",
        "id": "field-001",
        "page": 1,
        "positionX": 100,
        "positionY": 650,
        "width": 200,
        "height": 60,
        "allowedSignatureTypes": [
          { "signatureType": "ClickToSignSignature" },
          { "signatureType": "DrawToSignSignature" }
        ]
      },
      "recipientId": "1a2b3c4d-1234-1234-1234-ef0123456789",
      "sortOrder": 1
    }
  ]
}
```

- `positionX` / `positionY` are the coordinates of the field's top-left corner on the page.
- `allowedSignatureTypes` controls which signing methods the recipient can choose. If you leave it `null`, the organization defaults apply.
- `sortOrder` sets the sequence in which fields are presented to the signer.
**Response `204 No Content`**


Your template is now fully configured.

## Part 2 — Create an Envelope from the Template

### Step 6 — Create an Envelope

Instantiate a new envelope from the template with a single call. The template's document, stages, recipients, and field placements are all copied into the new envelope automatically. No request body is required.

```http
POST /api/v1/organizations/{organizationId}/templates/{templateId}/create-envelope
```

**Response `200 OK`**

```json
{
  "createdEnvelopeId": "a1b2c3d4-1234-1234-1234-ef1234567890"
}
```

The returned `createdEnvelopeId` is a standard envelope ID. From this point on, work with the envelope exactly as you would any other — you can optionally edit it before sending, or send it immediately.

### Step 7 — Send the Envelope

Transition the envelope from `draft` to `sent`. This triggers the invitation email to your recipient.

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send
```

No request body required. Use `createdEnvelopeId` as the `envelopeId`.

**Response `200 OK`**

```json
{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890",
}
```

### Step 8 — Check the Envelope Status

Poll this endpoint to track progress.

```http
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}
```

**Response `200 OK`**

```json
{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890",
  "name": "Standard Lease Agreement",
  "status": "completed",
  "sentAt": "2026-04-20T10:05:00Z"
  ...
}
```

### Step 9 — Download the Signed Document

Once the envelope is `completed`, retrieve the signed file and audit trail.

**List available artifacts:**

```http
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts
```

```json
{
  "artifacts": [
    {
      "id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
      "name": "LeaseAgreement_signed.pdf",
      "type": "CompletedFile"
    },
    {
      "id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
      "name": "AuditTrail.pdf",
      "type": "AuditTrail"
    }
  ]
}
```

**Download a specific artifact:**

```http
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}
```

Returns the file as a binary stream (`application/pdf`).