Skip to main content

Save column mappings as a roster upload template

POST 
/roster-upload/:templateId/column-mapping/template

Creates a new roster upload template from a set of confirmed column mappings, or updates an existing one.

When to use: call this after reviewing the analysis returned by POST /roster-upload/{templateId}/column-mapping; this endpoint persists the mappings the user confirmed.

Preconditions: supply the tenant-id header and the templateId the mappings belong to. In the request body, set updateExistingTemplate to true to update the template identified by templateId, or omit it (or set it to false) to create a new one; mappings carries the confirmed field list and jobType selects the field catalogue. A null mappings list is treated as an empty list rather than rejected. templateName and templateDescription are not enforced by this endpoint on either create or update. 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).

Validation: the field mappings are validated before anything is written. If validation fails the request returns 400 carrying the individual field errors and no template state is changed.

What you get back: the resulting template record, including templateId, templateUrl, schemaUrl, the persisted fields, and status. Both creation and update return 200.

Side effects: on success the confirmed mappings are also written to a tenant-scoped column mapping cache, which later mapping analyses use to suggest matches for unmapped headers. That cache write is fail-open - if it fails the template is still saved and the request still succeeds. The operation is not idempotent: submitting the same mappings twice with updateExistingTemplate set to false creates two templates.

Request​

Responses​

The saved template, including its identifier, hosted URLs, and the persisted field mappings. Returned for both creation and update.