Sign in
latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

Roster upload

Retrieve column mappings for a roster upload template

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.

What you get back: five lists - mapped (headers resolved to a template field), unMapped (headers matched by neither the template nor the cache), 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.

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

Path parameters

templateIdstring required

Identifier of the roster upload template to match the submitted column headers against. Obtained from the tenant's template list.

Headers

tenant-idstring required

Unique identifier of the tenant whose roster upload configuration is being read. Obtained from your account configuration.

Request body

columnsstring[]

Raw column headers exactly as they appear in the uploaded file's header row. Order is preserved in the analysis.

jobType'PRACTITIONER' | 'FACILITY' | 'GROUP'
compareAgainstTemplateboolean

When true, clears mappedEntity on every returned system field and enables verbose diagnostic logging. Does not change how columns are matched, and the operation stays read-only either way. Defaults to false.

Example request

{
  "columns": [
    "NPI",
    "First Name",
    "Provider Nickname"
  ]
}

Response

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

unMappedstring[]

Headers matched by neither the template nor the tenant's mapping cache. These need a mapping decision before the template can be saved.

skippedstring[]

Headers matching a template field that was explicitly excluded on a previous mapping, so they are excluded again automatically.

Example response

{
  "mapped": [
    {
      "name": "First Name",
      "mappedKey": "firstName",
      "mappedEntity": "practitioner",
      "entityGroup": "license",
      "validationRegex": "^\\d{10}$",
      "separator": ";"
    }
  ],
  "unMapped": [
    "Provider Nickname"
  ],
  "skipped": [
    "Internal Notes"
  ],
  "systemFields": [
    {
      "name": "First Name",
      "mappedKey": "firstName",
      "mappedEntity": "practitioner",
      "entityGroup": "license",
      "validationRegex": "^\\d{10}$",
      "separator": ";"
    }
  ],
  "cachedMapped": [
    {
      "name": "First Name",
      "mappedKey": "firstName",
      "mappedEntity": "practitioner",
      "entityGroup": "license",
      "validationRegex": "^\\d{10}$",
      "separator": ";"
    }
  ]
}