---
title: "Retrieve grouping metadata for tenant system fields"
method: GET
path: "/roster-upload/system-fields"
tags: ["Roster upload"]
---

# Retrieve grouping metadata for tenant system fields

`GET /roster-upload/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.

## Query parameters

- `jobType` 'PRACTITIONER' | 'FACILITY' | 'GROUP', required

## Headers

- `tenant-id` string, required

## Response `200`

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

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

## Other responses

- `400` — Returned when the `tenant-id` header is missing or blank, or the `jobType` query parameter is absent. Supply both and retry.
- `401` — Returned when the request carries no valid authentication.
- `403` — Returned when the column mapping feature is disabled for the tenant (`reason` is `FEATURE_DISABLED`) or the caller lacks the UPDATE_ROSTER_UPLOAD permission. Ask an administrator to enable the feature or grant the permission.
- `500` — Returned when the grouping metadata cannot be resolved. Retry; if the failure persists, contact support.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)