---
title: "Finalize a template by generating its validation schema"
method: PUT
path: "/templates/{id}/approve"
tags: ["Template"]
---

# Finalize a template by generating its validation schema

`PUT /templates/{id}/approve`

Completes the legacy three-step template flow: generates the JSON validation schema from the submitted field mappings (honoring the tenant-specific schema, when one is configured), uploads it to GCS as `schema.json`, and moves the template record to status `success` with its `template`/`schema` object paths recorded.

**When to use:** Call this as step 3 of the legacy flow, after `PUT /templates/{id}` has confirmed the column mappings. Templates created via `POST /templates/single-step` or the scratch builder are already approved and must not go through this endpoint.

**How:** Supply `{id}` and the required `tenant-id` header. The body is required and is not merely re-validated: the submitted `fields` are the direct input to schema generation, so send the same mappings confirmed in step 2. The same validation rules as `PUT /templates/{id}` apply - every stored CSV column must be mapped and every non-skipped `mappedKey` must be a known system field (400 otherwise), and a `GROUP` `jobType` requires the tenant's `supportGroupRosters` configuration.

**Returns:** An `ApproveTemplateResponse` with the `fields` the schema was generated from and the final `status`: `success` on completion, or `failure` when schema generation or upload failed with an I/O error - in that case the template record is left unchanged (it remains `in-progress`) and the call can be retried.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- TemplateUpdateRequest — Confirmed column-to-field mappings for a template. Used as the request body of `PUT /templates/{id}` and `PUT /templates/{id}/approve`; `PUT /templates/{id}` also echoes this shape back as its response.
  - `jobType` 'PRACTITIONER' | 'FACILITY' | 'GROUP'
  - `fields` Field[] — Column mappings to record. Must contain one entry for every header column of the template's stored `template.csv` (unmapped columns cause a 400); columns to ignore must be sent with the `[skipped]` sentinel as `mappedKey`. Each non-skipped entry's `mappedKey` must be a known system field unless `mappedEntity` is provided.
    - `name` string — CSV column header this mapping applies to, exactly as it appears in the roster file.
    - `mappedKey` string — Key of the Certify system field this column maps to, from the field catalog returned by `GET /templates/fields`. The sentinel `[skipped]` marks a column the user explicitly chose not to map: skipped columns persist in the template/mappings CSVs but are excluded from the generated validation schema.
    - `mappedEntity` string — Entity that owns the mapped attribute (for example `practitioner` or `location`). When set, `mappedKey` is accepted as-is instead of being validated against the system-field catalog.
    - `entityGroup` string — Group label linking columns that belong to the same repeating entity instance (a multiple-value group), so related columns are ingested together.
    - `isRequired` boolean — Whether every roster row must supply a value for this column; drives the `required` constraint in the generated validation schema.
    - `isStaticField` boolean — Catalog metadata: whether the mapped system field is a static (fixed-value) field rather than one populated from roster data.
    - `isSingleSelect` boolean — Catalog metadata: whether the mapped system field accepts a single value from a fixed option list.
    - `validationRegex` string — Regular expression applied to this column's values during roster validation. Rows whose values do not match are rejected.
    - `description` string — Human-readable description of the mapped system field, from the field catalog.
    - `enum` string[] — Allowed values for enum-type system fields; roster values outside this list fail validation. Absent for free-form fields.
    - `separator` string — Literal separator character used to split a single cell value into multiple tokens for multi-value attributes. Blank or absent defaults to a comma at schema-generation time.
    - `singleSelect` boolean
    - `skipped` boolean

## Response `200`

The mappings the schema was generated from and the final approval status. Note that `failure` is reported with HTTP 200 - check the body's `status`, not just the status code.

- ApproveTemplateResponse — Outcome of a template approval: the mappings the validation schema was generated from and the resulting status.
  - `fields` Field[] — The column mappings the schema generation ran against - an echo of the request body's `fields`.
    - `name` string — CSV column header this mapping applies to, exactly as it appears in the roster file.
    - `mappedKey` string — Key of the Certify system field this column maps to, from the field catalog returned by `GET /templates/fields`. The sentinel `[skipped]` marks a column the user explicitly chose not to map: skipped columns persist in the template/mappings CSVs but are excluded from the generated validation schema.
    - `mappedEntity` string — Entity that owns the mapped attribute (for example `practitioner` or `location`). When set, `mappedKey` is accepted as-is instead of being validated against the system-field catalog.
    - `entityGroup` string — Group label linking columns that belong to the same repeating entity instance (a multiple-value group), so related columns are ingested together.
    - `isRequired` boolean — Whether every roster row must supply a value for this column; drives the `required` constraint in the generated validation schema.
    - `isStaticField` boolean — Catalog metadata: whether the mapped system field is a static (fixed-value) field rather than one populated from roster data.
    - `isSingleSelect` boolean — Catalog metadata: whether the mapped system field accepts a single value from a fixed option list.
    - `validationRegex` string — Regular expression applied to this column's values during roster validation. Rows whose values do not match are rejected.
    - `description` string — Human-readable description of the mapped system field, from the field catalog.
    - `enum` string[] — Allowed values for enum-type system fields; roster values outside this list fail validation. Absent for free-form fields.
    - `separator` string — Literal separator character used to split a single cell value into multiple tokens for multi-value attributes. Blank or absent defaults to a comma at schema-generation time.
    - `singleSelect` boolean
    - `skipped` boolean
  - `status` string — `success` when the JSON schema was generated, uploaded to GCS, and the template record moved to `success`; `failure` when schema generation or upload failed with an I/O error, in which case the template record is left unchanged (it remains `in-progress`) and the call can be retried.

## Other responses

- `400` — A column of the stored `template.csv` is missing from `fields`, a `mappedKey` is not a known system field, or the requested `GROUP` type is not enabled for the tenant. Each entry in `errors` names the offending column in `title` and the cause in `reason`; fix the payload and retry.
- `401` — Authentication required - supply a valid bearer token.
- `403` — The authenticated user lacks the `UPDATE_TEMPLATE` permission.
- `500` — Unexpected server-side failure (for example a data-layer outage). Safe to retry once the underlying issue clears.

---

[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)