Skip to main content

Start legacy two-step template upload with field suggestions

POST 
/templates

Creates a template record with status in-progress, uploads the raw file to GCS as template.csv, and runs column-to-field suggestion matching against the file's header row, returning ranked mapping suggestions per column.

When to use: Use this as step 1 of the legacy two-step flow when you want to inspect and edit the suggested field mappings before approving. If the mapping is already known, use POST /templates/single-step instead, which does everything in one call. After this call you must call PUT /templates/{id} to confirm the column mappings and then PUT /templates/{id}/approve to finalize the template.

How: Send a multipart/form-data request with the required tenant-id header and fields: name (display name), type (PRACTITIONER, FACILITY, or GROUP - GROUP requires the tenant's supportGroupRosters configuration, otherwise 400), description (optional), and file - a roster-shaped CSV whose header row supplies the column names to match. Unlike the single-step endpoint, no .csv extension check is applied here; the file is parsed as CSV regardless of its name. Columns with a previously confirmed mapping in the tenant's column-mapping cache return that single high-confidence match; all other columns are fuzzy-matched against the system-field catalog.

Returns: A TemplateUploadResponse with status in-progress and a data object carrying the new template's id, the per-column suggestions (fields), the full mappable field catalog for the roster type (allFields), and entity-group hints (entities). The template is not yet usable for roster uploads until the confirm and approve steps complete.

Request​

Responses​

The new template's ID plus per-column mapping suggestions and the full field catalog to review before confirming mappings.