---
title: Templates API
description: Create and manage reusable document templates with custom fields
---

# Templates API

The Templates API allows you to create reusable document templates with predefined fields. Templates speed up document creation by providing a standardized structure that can be used repeatedly.

## The Template Object

### Attributes

| Attribute     | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| `id`          | string | Unique template identifier             |
| `name`        | string | Template name                          |
| `description` | string | Template description                   |
| `category`    | string | Template category for organization     |
| `fields`      | array  | Array of field definitions             |
| `created_at`  | string | ISO 8601 creation timestamp            |
| `updated_at`  | string | ISO 8601 last update timestamp         |
| `usage_count` | number | Number of times template has been used |

### Example Object

```json
{
  "id": "tpl_abc123",
  "name": "Employment Contract",
  "description": "Standard employment agreement template",
  "category": "HR",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z",
  "usage_count": 45
}
```

## List Templates

Retrieve all templates for your organization.

### Endpoint

```
GET /api/v1/templates
```

### Required Scope

`seal:templates:read`

### Query Parameters

| Parameter  | Type   | Description                             |
| ---------- | ------ | --------------------------------------- |
| `limit`    | number | Number of results (max 100, default 20) |
| `cursor`   | string | Pagination cursor                       |
| `category` | string | Filter by category                      |

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates?category=HR",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  }
);

const { templates, has_more, next_cursor } = await response.json();
```

### cURL Example

```bash
curl -X GET "https://api.seal.nyc/api/v1/templates?category=HR" \
  -H "Authorization: Bearer ak_your_api_key_here"
```

## Get Template

Retrieve a single template by ID.

### Endpoint

```
GET /api/v1/templates/get?id={id}
```

### Required Scope

`seal:templates:read`

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates/get?id=tpl_abc123",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  }
);

const template = await response.json();
```

### cURL Example

```bash
curl -X GET "https://api.seal.nyc/api/v1/templates/get?id=tpl_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here"
```

## Get Template Fields

Retrieve field definitions for a template.

### Endpoint

```
GET /api/v1/templates/fields?id={id}
```

### Required Scope

`seal:templates:read`

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates/fields?id=tpl_abc123",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  }
);

const fields = await response.json();
```

### Response

```json
{
  "fields": [
    {
      "id": "field_1",
      "name": "employee_name",
      "label": "Employee Name",
      "type": "text",
      "required": true,
      "placeholder": "Enter full name"
    },
    {
      "id": "field_2",
      "name": "start_date",
      "label": "Start Date",
      "type": "date",
      "required": true
    },
    {
      "id": "field_3",
      "name": "salary",
      "label": "Annual Salary",
      "type": "number",
      "required": true
    }
  ]
}
```

## Create Template from Document

Create a new template from an existing document.

### Endpoint

```
POST /api/v1/templates
```

### Required Scope

`seal:templates:write`

### Request Body

| Field         | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `document_id` | string | Yes      | Source document ID   |
| `name`        | string | Yes      | Template name        |
| `description` | string | No       | Template description |
| `category`    | string | No       | Template category    |

### TypeScript Example

```typescript
const response = await fetch("https://api.seal.nyc/api/v1/templates", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document_id: "doc_xyz789",
    name: "Employment Contract",
    description: "Standard employment agreement",
    category: "HR",
  }),
});

const template = await response.json();
```

### cURL Example

```bash
curl -X POST https://api.seal.nyc/api/v1/templates \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_xyz789",
    "name": "Employment Contract",
    "category": "HR"
  }'
```

## Update Template

Update a template's metadata.

### Endpoint

```
PUT /api/v1/templates/update?id={id}
```

### Required Scope

`seal:templates:write`

### Request Body

| Field         | Type   | Description       |
| ------------- | ------ | ----------------- |
| `name`        | string | New template name |
| `description` | string | New description   |
| `category`    | string | New category      |

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates/update?id=tpl_abc123",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Updated Employment Contract",
      category: "Legal",
    }),
  }
);
```

## Delete Template

Permanently delete a template.

### Endpoint

```
DELETE /api/v1/templates/delete?id={id}
```

### Required Scope

`seal:templates:write`

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates/delete?id=tpl_abc123",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  }
);

const result = await response.json();
// Returns { "deleted": true } with 200 status
```

## Use Template

Create a new document from a template.

### Endpoint

```
POST /api/v1/templates/use?id={id}
```

### Required Scope

`seal:templates:read`

### Request Body

| Field         | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `title`       | string | Yes      | Document title       |
| `description` | string | No       | Document description |

### TypeScript Example

```typescript
const response = await fetch(
  "https://api.seal.nyc/api/v1/templates/use?id=tpl_abc123",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "John Doe Employment Contract",
      description: "Employment agreement for John Doe",
    }),
  }
);

const document = await response.json();
```

### Response

```json
{
  "id": "doc_new123",
  "title": "John Doe Employment Contract",
  "status": "draft",
  "created_from_template": "tpl_abc123",
  "created_at": "2024-01-27T15:00:00Z"
}
```

## Field Types

| Type        | Description            | Example Value      |
| ----------- | ---------------------- | ------------------ |
| `text`      | Single-line text input | "John Doe"         |
| `textarea`  | Multi-line text input  | "Full address..."  |
| `number`    | Numeric input          | 75000              |
| `date`      | Date picker            | "2024-02-01"       |
| `email`     | Email address          | "john@example.com" |
| `checkbox`  | Boolean checkbox       | true               |
| `select`    | Dropdown selection     | "option1"          |
| `signature` | Signature field        | (drawn signature)  |

## Next Steps

- **[Documents API](/docs/api-reference/documents)** - Create documents from templates
- **[Quick Start](/docs/getting-started/quick-start)** - Integration tutorial