latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

Roster upload

Retrieve grouping metadata for tenant system fields

Returns the grouping rules that apply to each of the tenant's system fields, keyed by the field's mappedKey.

When to use: call this while building the column mapping screen, to decide whether a mapped column additionally needs an Entity Group or a Separator input from the user. Pair it with POST /roster-upload/{templateId}/column-mapping, which returns the fields themselves but not their grouping rules.

Preconditions: supply the tenant-id header and the jobType query parameter; both are required and a missing or blank value returns 400. 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). Tenant-specific schema paths are used when the tenant has them configured; otherwise the platform default schemas apply.

What you get back: an object keyed by mappedKey, where each value carries up to four grouping descriptors - valueArrayGrouping (the column holds several values in one cell, separated by a delimiter), objectArrayGrouping (the column contributes to one entry of a repeating object, such as a license), objectGrouping (the column contributes to a single nested object, such as user-defined fields), and entityInstanceGrouping (the column belongs to a numbered instance of an entity, such as a second practice location). A field with no grouping rules is returned with all four descriptors absent. Read-only; no state is mutated.

get/roster-upload/system-fields

Query parameters

jobType'PRACTITIONER' | 'FACILITY' | 'GROUP' required

Entity catalogue whose system fields should be described. One of PRACTITIONER, FACILITY, or GROUP. Required - there is no default.

Headers

tenant-idstring required

Unique identifier of the tenant whose system fields are being read. Obtained from your account configuration.

Response

Grouping rules for the tenant's system fields, keyed by the field's mappedKey.

object required

Map keyed by system field name; each value carries that field's grouping metadata (group, label, ordering).