> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates and flows API for signing managers

> List, retrieve, update, and duplicate document templates. Browse and retrieve signing flows that define the guided signer walkthrough structure.

Templates define the documents and signer configuration for a signing package. Flows define the guided walkthrough experience presented to signers. Both are scoped to a location and managed through the endpoints below.

All endpoints in this group require a Clerk session JWT and enforce RBAC based on your session's module tiers. Managers see only templates and flows at locations they can access. Admins receive global access, capped at 500 rows per list response.

Check `caps.manager.templates` and `caps.manager.flows` in your [session payload](/api/signing/session) to determine which operations are available to your account before calling these routes.

***

## Templates

### List templates

Returns templates for the locations in your scope. Managers can optionally filter by location. Admins receive all templates globally (capped at 500). Results are ordered by `id` ascending.

```
GET /v1/signing/manager/templates
```

**Required tier:** `templates` at `"read"` or above, or admin.

<ParamField query="locationId" type="string">
  Numeric location ID to filter results. Managers specifying a location outside their scope receive `403`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.safeclose.com/v1/signing/manager/templates?locationId=204" \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

#### Response

<ResponseField name="templates" type="array" required>
  Array of `signing.templates` rows.
</ResponseField>

<ResponseField name="scope" type="string" required>
  `"managed"` for managers scoped to their accessible locations, or `"global"` for admins.
</ResponseField>

#### Error responses

| Status | Condition                                                                          |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | `locationId` is not a valid numeric string.                                        |
| `403`  | `templates` tier is `"none"`, or the specified `locationId` is outside your scope. |

***

### Get one template

Returns a single `signing.templates` row. The template's location must be in your scope.

```
GET /v1/signing/manager/templates/:templateId
```

**Required tier:** `templates` at `"read"` or above, or admin.

<ParamField path="templateId" type="string" required>
  Numeric template ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/manager/templates/55 \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

#### Response

The `signing.templates` row for the requested template.

#### Error responses

| Status | Condition                                                            |
| ------ | -------------------------------------------------------------------- |
| `400`  | `templateId` is not a valid numeric string.                          |
| `403`  | Insufficient tier, or the template's location is outside your scope. |
| `404`  | Template not found.                                                  |

***

### Update a template

Partially updates a template's `name` and/or `active` flag. You must supply at least one field. The template's location must be in your scope.

```
PATCH /v1/signing/manager/templates/:templateId
```

**Required tier:** `templates` at `"write"` or above, or admin.

<ParamField path="templateId" type="string" required>
  Numeric template ID.
</ParamField>

<ParamField body="name" type="string">
  New display name for the template. Minimum 1 character, maximum 500 characters.
</ParamField>

<ParamField body="active" type="boolean">
  Set to `false` to deactivate the template (prevents it from being selected when creating new signing packages) or `true` to re-activate it.
</ParamField>

<CodeGroup>
  ```bash cURL (rename and deactivate) theme={null}
  curl -X PATCH https://api.safeclose.com/v1/signing/manager/templates/55 \
    -H "Authorization: Bearer <clerk_jwt>" \
    -H "Content-Type: application/json" \
    -d '{"name": "UCC-1 Financing Statement v2", "active": false}'
  ```

  ```bash cURL (re-activate only) theme={null}
  curl -X PATCH https://api.safeclose.com/v1/signing/manager/templates/55 \
    -H "Authorization: Bearer <clerk_jwt>" \
    -H "Content-Type: application/json" \
    -d '{"active": true}'
  ```
</CodeGroup>

#### Response

<ResponseField name="template" type="object" required>
  The updated `signing.templates` row.
</ResponseField>

<CodeGroup>
  ```json Example response theme={null}
  {
    "template": {
      "id": "55",
      "locationId": "204",
      "name": "UCC-1 Financing Statement v2",
      "active": false,
      "pagesCount": 4,
      "signerNumbers": [1, 2],
      "completedSigningsCount": 12,
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-06-15T16:00:00.000Z"
    }
  }
  ```
</CodeGroup>

#### Error responses

| Status | Condition                                                                          |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | Invalid `templateId`, malformed body, or neither `name` nor `active` was provided. |
| `403`  | Insufficient tier, or the template's location is outside your scope.               |
| `404`  | Template not found.                                                                |

***

### Duplicate a template

Creates a copy of an existing template at the same location. The new template receives a `name` of `"Copy of <original name>"` and is otherwise an exact clone of the source row (pages count, signer numbers, explanation IDs, processing flags, tag, etc.). The `completedSigningsCount` on the copy is reset to `0`.

```
POST /v1/signing/manager/templates/:templateId/duplicate
```

**Required tier:** `templates` at `"write"` or above, or admin.

<ParamField path="templateId" type="string" required>
  Numeric ID of the template to clone.
</ParamField>

No request body.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.safeclose.com/v1/signing/manager/templates/55/duplicate \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

#### Response

<ResponseField name="template" type="object" required>
  The newly created `signing.templates` row representing the copy. Its `id` and `createdAt`/`updatedAt` are new; its `locationId` matches the source.
</ResponseField>

<CodeGroup>
  ```json Example response theme={null}
  {
    "template": {
      "id": "56",
      "locationId": "204",
      "name": "Copy of UCC-1 Financing Statement v2",
      "active": false,
      "pagesCount": 4,
      "signerNumbers": [1, 2],
      "completedSigningsCount": 0,
      "createdAt": "2025-06-15T16:05:00.000Z",
      "updatedAt": "2025-06-15T16:05:00.000Z"
    }
  }
  ```
</CodeGroup>

#### Error responses

| Status | Condition                                                            |
| ------ | -------------------------------------------------------------------- |
| `400`  | `templateId` is not a valid numeric string.                          |
| `403`  | Insufficient tier, or the template's location is outside your scope. |
| `404`  | Template not found.                                                  |

***

## Flows

Flows define the guided signing walkthrough sequence for a package—the order of explanation steps, the signer prompts, and any location-specific configuration. When you create a signing package with a `flowId`, the flow at that location determines the signer experience.

### List flows

Returns flows for the locations in your scope, optionally filtered by location. Admins receive all flows globally (capped at 500). Results are ordered by `id` ascending.

```
GET /v1/signing/manager/flows
```

**Required tier:** `flows` at `"read"` or above, or admin.

<ParamField query="locationId" type="string">
  Numeric location ID to filter results. Managers specifying a location outside their scope receive `403`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.safeclose.com/v1/signing/manager/flows?locationId=204" \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

#### Response

<ResponseField name="flows" type="array" required>
  Array of `signing.flows` rows in your scope.
</ResponseField>

<ResponseField name="scope" type="string" required>
  `"managed"` for scoped manager access, or `"global"` for admin access.
</ResponseField>

#### Error responses

| Status | Condition                                                                      |
| ------ | ------------------------------------------------------------------------------ |
| `400`  | `locationId` is not a valid numeric string.                                    |
| `403`  | `flows` tier is `"none"`, or the specified `locationId` is outside your scope. |

***

### Get one flow

Returns a single `signing.flows` row. The flow's location must be in your scope.

```
GET /v1/signing/manager/flows/:flowId
```

**Required tier:** `flows` at `"read"` or above, or admin.

<ParamField path="flowId" type="string" required>
  Numeric flow ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/manager/flows/18 \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

#### Response

The `signing.flows` row for the requested flow.

#### Error responses

| Status | Condition                                                        |
| ------ | ---------------------------------------------------------------- |
| `400`  | `flowId` is not a valid numeric string.                          |
| `403`  | Insufficient tier, or the flow's location is outside your scope. |
| `404`  | Flow not found.                                                  |

***

## Using templates and flows together

When creating a signing package via [`POST /v1/signing/manager/signings`](/api/signing/manager-signings#create-a-signing-package), you can supply a `flowId` to associate a specific walkthrough flow with the package. The `flowId` must reference a flow at the **same location** as the `locationId` you specify—a mismatch returns `400`.

Templates are not directly referenced when creating a package via API. They are used by the platform to populate a package's documents. Refer to your integration documentation for how templates are applied during package setup.

<Note>
  Neither templates nor flows can currently be created or deleted through the API. Use the Safeclose manager UI to create new templates and flows, then reference them by ID in API calls.
</Note>