--- title: "Retrieve a roster job with a file download link" method: GET path: "/roster/{id}" tags: ["Roster"] --- # Retrieve a roster job with a file download link `GET /roster/{id}` Returns a single roster import job, including a time-limited link to the file that was uploaded for it. **When to use:** call this to inspect the current status and metadata of one job, or to poll it after creating or reuploading a roster; to list every job for the tenant, use `GET /roster`. **Preconditions:** supply the `tenant-id` header and the roster job's `id`. **What you get back:** the roster job, carrying three pre-signed download links in its `data` object - `rosterFileUrl` for the uploaded file, `templateUrl` for the template it was mapped with, and `mappingsFileUrl` for the resolved column mappings. All three are generated per request and expire after seven days, so treat them as short-lived: follow them promptly rather than storing them. Read-only; no state is mutated. **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. ## Path parameters - `id` string, required ## Headers - `tenant-id` string, required ## Response `200` The roster job, including a time-limited download link for the uploaded file. - RosterResponse - `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 ## Other responses - `400` — Returned when the roster job cannot be read because the request is malformed or the download link could not be generated. - `401` — Returned when the request carries no valid authentication. - `403` — Returned when the caller lacks the READ_ROSTER permission for this tenant. - `404` — Returned when no roster job with the supplied `id` exists for the 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)