---
title: "Partially update a template, re-approving on file replacement"
method: PATCH
path: "/templates/{id}/single-step"
tags: ["Template"]
---

# Partially update a template, re-approving on file replacement

`PATCH /templates/{id}/single-step`

Updates one or more attributes (`name`, `description`, `type`, `file`) of an existing template. At least one must be provided; supplying none causes a 400.

**When to use:** Use this to rename a template, change its description or type, or replace its mappings CSV without going through the full create flow. For confirming column mappings in the legacy two-step flow use `PUT /templates/{id}` instead.

**How:** Send a `multipart/form-data` request with the required `tenant-id` header, `{id}` identifying an existing template for the tenant (404 otherwise), and any subset of the updatable fields. If `file` is supplied it must have a `.csv` extension and every mapping row must carry a mapped attribute (400 otherwise). A `type` of `GROUP` requires the tenant's `supportGroupRosters` configuration.

**Returns:** A `SingleStepTemplateFlowResponse`, with side effects depending on the branch taken. *With `file`:* the template's existing column records are deleted, new `template.csv`/`mappings.csv` objects are uploaded to GCS, new column records are created, `schema.json` is regenerated, and the resulting status (`success`, or `failure` if schema generation failed) is persisted and returned with the refreshed `fields`. *Without `file`:* only the metadata changes; the stored columns, artifacts, and status are preserved, and the response echoes the existing `fields` and status with the stored artifact object paths.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Response `200`

The updated template's resolved column mappings, status, and artifact object paths.

- SingleStepTemplateFlowResponse — Result of a single-step template create or update: the resolved column mappings, final status, and the GCS object paths of the template artifacts.
  - `fields` Field[] — The template's resolved column mappings. After a file upload these are the mappings extracted from the uploaded mappings CSV; after a metadata-only update they are the template's existing stored columns.
    - `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 — Final template status. `success` when the validation schema was generated and the template is ready for roster uploads; `failure` when schema generation failed with an I/O error. Metadata-only updates preserve and return the template's existing status.
  - `templateId` string — Server-generated ID of the created or updated template.
  - `templateUrl` string — GCS object path (not a signed URL) of the stored template CSV. Fetch a signed download URL via `GET /templates/{id}`, which returns it as `templateUrl` in the record's `data`.
  - `schemaUrl` string — GCS object path (not a signed URL) of the generated JSON validation schema. Fetch a signed download URL via `GET /templates/{id}`, which returns it as `schemaUrl` in the record's `data`.

## Other responses

- `400` — No updatable field was provided, the `tenant-id` header is blank, the file is not a `.csv`, a mapping row is missing its mapped attribute, or the requested `GROUP` type is not enabled for the tenant. Correct the request and retry.
- `401` — Authentication required - supply a valid bearer token.
- `403` — The authenticated user lacks the `UPDATE_TEMPLATE` permission.
- `404` — No template with the given `{id}` exists for the tenant. Verify the ID against `GET /templates`.
- `500` — Unexpected server-side failure (for example a GCS or 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)