---
title: "List tenant-scoped templates with filters"
method: GET
path: "/templates"
tags: ["Template"]
---

# List tenant-scoped templates with filters

`GET /templates`

Returns a paginated list of roster templates belonging to the requesting tenant.

**When to use:** Call this to browse available templates before creating a roster upload, or to check the processing status of previously created templates. For a single template's full details use `GET /templates/{id}`; for the ordered column definitions of a scratch-built template use `GET /templates/{id}/columns`.

**How:** Supply the required `tenant-id` header. Page with `page` (0-based) and `size` (defaults to 50 when omitted or non-positive, silently clamped to a maximum of 100). Filter with `status` (exact, case-sensitive match; the values written by this API are `in-progress`, `success`, and `failure`), `type` (exact, case-sensitive match: `PRACTITIONER`, `FACILITY`, or `GROUP`), and/or `templateName` (case-insensitive substring match).

**Returns:** A paginated envelope whose `data` items are template records; each record's `data` object includes the template's name, type, status, and a `mappingsUrl` - a V4-signed GCS download URL for the column-mappings file, valid for 7 days, generated at request time and never stored. The envelope's `links` is always `null` on this endpoint; `totalCount` carries the number of matches across all pages. Read-only; no state is changed.

## Query parameters

- `page` integer
- `size` integer
- `status` string
- `templateName` string
- `type` string

## Headers

- `tenant-id` string, required

## Response `200`

One page of the tenant's templates matching the filters, each with a request-time signed `mappingsUrl` injected into its `data` object.

- PagedTemplateResponse — A single page of roster templates.
  - `data` RosterTemplateResponseSchema[] — Template records on this page, each with a request-time `mappingsUrl` signed download URL injected into its `data` object.
    - `id` string — Server-generated unique identifier of the template.
    - `tenantId` string — Tenant that owns the template.
    - `createdAt` string, date-time
    - `createdBy` string — ID of the user who created the template.
    - `updatedAt` string, date-time
    - `updatedBy` string — ID of the user who last updated the template.
    - `data` object — Template payload. Persisted keys: `templateName`, `description`, `status` (`in-progress` while awaiting mapping confirmation/approval, `success` once approved, `failure` when a re-approval's schema generation failed), `type` (`PRACTITIONER`, `FACILITY`, or `GROUP`), plus - once approved - `template` and `schema` (GCS object paths of the template CSV and generated JSON schema). Responses additionally inject short-lived signed download URLs generated at request time and never stored: `mappingsUrl` on both list and detail reads, and `templateUrl`/`schemaUrl` on the detail read when the underlying objects exist. Signed URLs are V4-signed and valid for 7 days.
  - `links` PageLinks1
    - `self` string
    - `next` string
    - `prev` string
  - `totalCount` integer — Total number of templates matching the filters, across all pages.

## Other responses

- `400` — The pagination or filter parameters were rejected by the data layer (for example a malformed value). Correct the query parameters and retry.
- `401` — Authentication required - supply a valid bearer token.
- `403` — The authenticated user lacks the `READ_TEMPLATE` permission.
- `500` — Unexpected server-side failure (for example a GCS or data-layer outage). Safe to retry; the operation is read-only.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)