---
title: "Suggest column-to-attribute mappings for a not-yet-created template"
method: POST
path: "/templates/scratch/suggest-mappings"
tags: ["Template"]
---

# Suggest column-to-attribute mappings for a not-yet-created template

`POST /templates/scratch/suggest-mappings`

Given a list of column names parsed client-side from an uploaded file (CP-31960), returns ranked mapping suggestions per column. Columns with a confirmed prior mapping in the tenant-scoped column mapping cache are returned as a single high-confidence suggestion; all other columns are fuzzy-matched against system fields.

## Headers

- `tenant-id` string, required

## Request body

- SuggestColumnMappingsRequest
  - `jobType` 'PRACTITIONER' | 'FACILITY' | 'GROUP'
  - `columnNames` string[]
  - `sampleValues` array[]
    - string[]

## Response `200`

Suggestions generated successfully

- FieldSuggestion[]
  - `name` string — CSV column header the suggestions apply to, exactly as it appears in the uploaded file.
  - `suggestedMatches` Field[] — Candidate system-field mappings for this column, best match first. A column with a previously confirmed mapping in the tenant's column-mapping cache returns that single high-confidence match; otherwise candidates come from fuzzy-matching the header against the system-field catalog. Empty when nothing scored above the match threshold.
    - `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` — Invalid input or request
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `500` — Internal server error

---

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