Skip to main content

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. By default a cache hit is also kept in unMapped, so render cachedMapped as pre-filled suggestions for those headers.

What you get back: five lists - mapped (headers resolved to a template field), unMapped (headers with no template match), 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.

Request​

Responses​

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