Sign in
latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

Roster upload

Save column mappings as a roster upload 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.

post/roster-upload/{templateId}/column-mapping/template

Path parameters

templateIdstring required

Identifier of the roster upload template to create or update. Obtained from the tenant's template list.

Headers

tenant-idstring required

Tenant identifier

Request body

updateExistingTemplateboolean

When true, updates the template named by the path parameter; when false or omitted, creates a new template. Creating twice with the same mappings produces two templates.

jobType'PRACTITIONER' | 'FACILITY' | 'GROUP'
templateNamestring

Human-readable name for the template, shown when choosing a template for a future upload. Not enforced by this endpoint on create or update.

templateDescriptionstring

Longer note describing what this template is for. Not enforced by this endpoint on create or update.

Example request

{
  "mappings": [
    {
      "name": "First Name",
      "mappedKey": "firstName",
      "mappedEntity": "practitioner",
      "entityGroup": "license",
      "validationRegex": "^\\d{10}$",
      "separator": ";"
    }
  ],
  "templateName": "Florida Blue Practitioner Roster",
  "templateDescription": "Monthly practitioner roster layout"
}

Response

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

statusstring

Final template status. success when the validation schema was generated and the template is ready for roster uploads; failure when schema generation failed with an I/O error. Metadata-only updates preserve and return the template's existing status.

templateIdstring

Server-generated ID of the created or updated template.

templateUrlstring

GCS object path (not a signed URL) of the stored template CSV. Fetch a signed download URL via GET /templates/{id}, which returns it as templateUrl in the record's data.

schemaUrlstring

GCS object path (not a signed URL) of the generated JSON validation schema. Fetch a signed download URL via GET /templates/{id}, which returns it as schemaUrl in the record's data.

Example response

{
  "fields": [
    {
      "name": "First Name",
      "mappedKey": "firstName",
      "mappedEntity": "practitioner",
      "entityGroup": "license",
      "validationRegex": "^\\d{10}$",
      "separator": ";"
    }
  ],
  "status": "success",
  "templateId": "3f8e2b6c-9d41-4a7b-b6a0-5e2f8c1d9a37",
  "templateUrl": "roster/templates/3f8e2b6c-9d41-4a7b-b6a0-5e2f8c1d9a37/template.csv",
  "schemaUrl": "roster/templates/3f8e2b6c-9d41-4a7b-b6a0-5e2f8c1d9a37/schema.json"
}