---
title: "Retrieve column mappings for a roster upload template"
method: POST
path: "/roster-upload/{templateId}/column-mapping"
tags: ["Roster upload"]
---

# Retrieve column mappings for a roster upload template

`POST /roster-upload/{templateId}/column-mapping`

Matches the raw column headers of an uploaded roster file against a named roster upload template and reports which headers resolve to known fields.

**When to use:** call this after reading the header row of the uploaded file and before persisting anything, then pass the resolved mappings to `POST /roster-upload/{templateId}/column-mapping/template` to save them as a template.

**Preconditions:** supply the `tenant-id` header and a `templateId` that exists for that tenant; in the request body, `columns` carries the raw header strings read from the uploaded file and `jobType` selects which field catalogue to match against. The tenant must have the column mapping feature enabled and the caller must hold the UPDATE_ROSTER_UPLOAD permission - both failures return 403, distinguished by the `reason` field of the error body (`FEATURE_DISABLED` identifies the feature-flag case).

**Matching behaviour:** headers are matched to template fields by exact name only; there is no fuzzy matching. A header matching a field that was explicitly skipped on a previous mapping is reported under `skipped` rather than `mapped`. Headers with no template match are then looked up in the tenant's column mapping cache, and any hits are returned under `cachedMapped` as suggestions.

**What you get back:** five lists - `mapped` (headers resolved to a template field), `unMapped` (headers matched by neither the template nor the cache), `skipped` (headers matching a previously excluded field), `systemFields` (platform-managed fields populated by the system rather than by file columns), and `cachedMapped` (suggested mappings recovered from the tenant cache). Setting `compareAgainstTemplate` to `true` clears `mappedEntity` on every `systemFields` entry and enables verbose per-column diagnostic logging; it does not change how columns are matched. The operation is read-only under either setting - no template, mapping, or cache state is written.

## Path parameters

- `templateId` string, required

## Headers

- `tenant-id` string, required

## Request body

- GetUploadMappingsRequest — Column headers read from an uploaded roster file, submitted for mapping analysis.
  - `columns` string[] — Raw column headers exactly as they appear in the uploaded file's header row. Order is preserved in the analysis.
  - `jobType` 'PRACTITIONER' | 'FACILITY' | 'GROUP'
  - `compareAgainstTemplate` boolean — When true, clears mappedEntity on every returned system field and enables verbose diagnostic logging. Does not change how columns are matched, and the operation stays read-only either way. Defaults to false.

## Response `200`

Mapping analysis for the submitted column headers, split into matched, unmatched, skipped, system-managed, and cache-suggested fields.

- GetUploadMappingsResponse — Result of matching a file's column headers against a roster upload template. Every submitted header appears in exactly one of mapped, unMapped, or skipped.
  - `mapped` Field[] — Headers matched to a template field by exact name, each carrying the system field it resolves to. Matching is exact-name only; there is no fuzzy matching.
    - `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
  - `unMapped` string[] — Headers matched by neither the template nor the tenant's mapping cache. These need a mapping decision before the template can be saved.
  - `skipped` string[] — Headers matching a template field that was explicitly excluded on a previous mapping, so they are excluded again automatically.
  - `systemFields` Field[] — Platform-managed fields available for this job type. They are populated by the system rather than driven by file columns, and are returned so the mapping UI can offer them. When compareAgainstTemplate is true, mappedEntity is cleared on each entry.
    - `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
  - `cachedMapped` Field[] — Suggested mappings for headers the template did not match, recovered from the tenant's column mapping cache of previously confirmed choices. Suggestions only - nothing is applied until the mappings are saved.
    - `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

## Other responses

- `400` — Bad Request
- `401` — Returned when the request carries no valid authentication.
- `403` — Returned when the column mapping feature is disabled for the tenant (`reason` is `FEATURE_DISABLED`) or the caller lacks the UPDATE_ROSTER_UPLOAD permission. Ask an administrator to enable the feature or grant the permission.
- `404` — Returned when no template with the supplied `templateId` exists for the tenant. Verify the identifier against the tenant's template list.
- `500` — Returned when the mapping analysis fails unexpectedly. Retry; if the failure persists, contact support.

---

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