---
title: "List roster jobs for the tenant"
method: GET
path: "/roster"
tags: ["Roster"]
---

# List roster jobs for the tenant

`GET /roster`

Returns a page of roster import jobs belonging to the tenant named in the `tenant-id` header.

**When to use:** call this to browse or monitor roster jobs; for a single job, use `GET /roster/{id}`, which additionally returns a download link for the uploaded file.

**Pagination:** three schemes are available and exactly one should be used per request - offset paging with `page` and `size`, forward cursor paging with `startAfterId`, or backward cursor paging with `endAtId`. Combining them in a single request produces undefined results.

**Sorting and filtering:** `sortBy` chooses the field to order by and defaults to `createdAt`, while `sortDirection` accepts `ASC` or `DESC` and defaults to `DESC`. The optional `filter` parameter takes a URL-encoded JSON object supporting `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, and `contains`; `tenantId` is applied automatically from the header and must not be included.

**What you get back:** an envelope carrying the roster jobs in `data`, along with pagination links and a total count where the underlying store reports one. Read-only; no state is mutated. Note: when the upstream data layer fails (including an unparseable `filter`), this endpoint currently returns 200 with an empty body rather than an error status - treat an empty (non-envelope) body as a retryable failure, not as an empty result set.
**Fields carried in `data`.** A roster job's payload is a free-form object, so its keys are documented here rather than as schema properties. Not every key is present at every stage - counters and result keys appear as processing progresses.

*Status and type*
- `status`: current stage of the job. Each value means:
  - `PENDING`: accepted and queued; validation has not started.
  - `PRE_PROCESSING`: held for review before validation, for uploads that require it.
  - `VALIDATION_IN_PROGRESS`: rows are being checked against the roster's schema.
  - `VALIDATION_FAILED`: validation finished and at least one row failed; the job waits for corrections.
  - `VALIDATED`: every row passed validation; the job is waiting for an approve or reject decision.
  - `REVALIDATE`: corrected rows have been resubmitted and validation is running again.
  - `APPROVED`: the import was approved and ingestion has been queued.
  - `IN_PROGRESS`: rows are being written into the platform.
  - `COMPLETED`: ingestion finished; `completedRecords` and `failedRecords` report the outcome.
  - `FAILED`: the job stopped on an error and did not finish.
  - `CANCELLED`: the import was rejected, or the job was cancelled before ingestion.
- `jobType`: kind of entity the file contains - PRACTITIONER, FACILITY, or GROUP (GROUP uploads require the tenant's supportGroupRosters configuration).
- `templateId`: identifier of the roster template describing the file's column layout.
- `description`: free-text note supplied when the roster was uploaded.

*File*
- `filename`: name of the file currently attached to the job.
- `filePath`: storage path of that file, relative to the bucket.
- `bucketName`: storage bucket holding the file.
- `sheetName`: worksheet read from the file, for .xlsx uploads only.
- `initialFilename`, `initialFilePath`: the file first uploaded, retained after a reupload replaces it.
- `uploadCount`: how many times a file has been uploaded to this job; 1 until the first reupload.
- `orderedFileColumns`: the file's column headers, in the order they appear in the header row.

*Counters* (populated as validation and ingestion progress)
- `totalRecords`: rows found in the file.
- `validRecords`, `invalidRecords`: rows that passed and failed validation.
- `completedRecords`, `failedRecords`: rows that were ingested successfully and rows that were not.

*Links* (generated per request on the single-job read, and short-lived)
- `rosterFileUrl`: time-limited link to the uploaded roster file.
- `templateUrl`: time-limited link to the template the roster was mapped with.
- `mappingsFileUrl`: time-limited link to the resolved column mappings.

*Results*
- `failureReasons`: validation or ingestion errors explaining why rows did not succeed.
- `importedAt`: when ingestion finished, as an ISO-8601 timestamp in UTC.
- `roster-export-path`, `roster-export-url`: storage path and time-limited link for the failed-records export, present once one has been generated.

## Query parameters

- `endAtId` string
- `filter` string
- `page` integer
- `size` integer
- `sortBy` string
- `sortDirection` string
- `startAfterId` string

## Headers

- `tenant-id` string, required

## Response `200`

A page of roster jobs for the tenant, ordered by the requested sort field.

- RosterJobsPage — One page of roster import jobs.
  - `data` RosterResponse[] — The roster jobs in this page.
    - `id` string
    - `tenantId` string
    - `templateId` string
    - `createdAt` string, date
    - `createdBy` string
    - `updatedAt` string, date
    - `updatedBy` string
    - `data` RosterJobData — Payload of a roster import job. Keys appear as processing progresses - none is guaranteed present at every stage, and new keys may be introduced by newer features, so treat unknown keys as valid. Key names mirror RosterDataRecord.
      - `status` 'PENDING' | 'IN_PROGRESS' | 'VALIDATION_IN_PROGRESS' | 'VALIDATION_FAILED' | 'PRE_PROCESSING' | 'VALIDATED' | 'COMPLETED' | 'APPROVED' | 'PARTIAL_IMPORTED' | 'REVALIDATE' | 'FAILED' | 'CANCELLED' — Current stage of the job. See the roster read operations' descriptions for the meaning of each value.
      - `jobType` 'PRACTITIONER' | 'FACILITY' | 'GROUP' — Kind of entity the file contains. GROUP uploads require the tenant's supportGroupRosters configuration.
      - `templateId` string — Identifier of the roster template describing the file's column layout.
      - `description` string — Free-text note supplied when the roster was uploaded.
      - `filename` string — Name of the file currently attached to the job.
      - `filePath` string — Storage path of that file, relative to the bucket.
      - `bucketName` string — Storage bucket holding the file.
      - `sheetName` string — Worksheet read from the file, for .xlsx uploads only.
      - `initialFilename` string — The file first uploaded, retained after a reupload replaces it.
      - `initialFilePath` string — Storage path of the first uploaded file, retained after a reupload.
      - `uploadCount` integer — How many times a file has been uploaded to this job; 1 until the first reupload.
      - `orderedFileColumns` string — The file's column headers in the order they appear in the header row, joined by the ",/" separator.
      - `totalRecords` integer — Rows found in the file.
      - `validRecords` integer — Rows that passed validation.
      - `invalidRecords` integer — Rows that failed validation.
      - `completedRecords` integer — Rows that were ingested successfully.
      - `failedRecords` integer — Rows that could not be ingested.
      - `rosterFileUrl` string — Time-limited link to the uploaded roster file. Present on the single-job read only.
      - `templateUrl` string — Time-limited link to the template the roster was mapped with. Present on the single-job read only.
      - `mappingsFileUrl` string — Time-limited link to the resolved column mappings. Present on the single-job read only.
      - `failureReasons` string — Validation or ingestion errors explaining why rows did not succeed.
      - `importedAt` string — When ingestion finished, as an ISO-8601 timestamp in UTC.
      - `roster-export-path` string — Storage path of the failed-records export, present once one has been generated.
      - `roster-export-url` string — Time-limited link to the failed-records export, present once one has been generated.
    - `invalidCount` integer
    - `validCount` integer
    - `completedCount` integer
    - `failedCount` integer
  - `links` PageLinks1
    - `self` string
    - `next` string
    - `prev` string
  - `totalCount` integer — Total number of roster jobs matching the request, when the underlying store reports one.

## Other responses

- `401` — Returned when the request carries no valid authentication.
- `403` — Returned when the caller lacks the READ_ROSTER permission for this tenant.

---

[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)