--- title: "Replace the file on an existing roster job" method: PUT path: "/roster/{rosterId}/reupload" tags: ["Roster"] --- # Replace the file on an existing roster job `PUT /roster/{rosterId}/reupload` Swaps in a corrected file for a roster job that already exists and starts its processing over. **When to use:** call this when the original upload contained errors and you have a fixed version of the whole file; to correct individual rows instead, use the roster row draft endpoints, and to begin an unrelated import, use `POST /roster`. **Preconditions:** send a multipart request carrying the `file` part, the `tenant-id` header, and the `rosterId` of the job to replace. Accepted formats are CSV, XLSX, TSV, and JSON; when the file is an `.xlsx`, `sheetName` names the worksheet to read. Text (`.txt`) files are accepted on first upload but cannot be used for a reupload. The roster must not be mid-flight: a job in `VALIDATION_IN_PROGRESS`, `IN_PROGRESS`, or `VALIDATED` state is rejected with 409. Beyond that, what is allowed depends on the caller - internal provider data administrators may reupload any job that is not mid-flight, while other callers may only reupload jobs in `VALIDATION_FAILED`, `FAILED`, `COMPLETED`, or `CANCELLED` state. **What you get back:** the updated roster job. Its status restarts the pipeline - `PENDING` when validation is dispatched immediately, or `PRE_PROCESSING` when the upload is routed for review first - so read the returned status rather than assuming validation has begun. **Side effects:** the stored file is replaced, the previous export link is discarded, the upload counter is incremented, and validation is re-run from the beginning. Not idempotent - each call replaces the file and restarts processing. ## Path parameters - `rosterId` string, required ## Headers - `tenant-id` string, required ## Response `200` The updated roster job, carrying the replacement file details and the status its processing restarted at. - 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 replacement file is rejected. A `.txt` file is rejected with the standard error envelope shown below; a missing `file` part or an `.xlsx` without a `sheetName` is rejected with a plain-text message (`No file uploaded`, `Sheet name is required for excel file`). Correct the file and retry. - `401` — Returned when the request carries no valid authentication. - `403` — Returned when the caller lacks the UPDATE_ROSTER permission for this tenant. - `409` — Returned when the roster cannot accept this reupload - it is mid-flight, the caller's role does not permit reuploading a job in its current state, or no roster job with the supplied `rosterId` exists for the tenant (a missing roster is currently reported as 409, not 404). Read the error message to distinguish; wait and retry only when the job is mid-flight. - `500` — Returned when the reupload could not be completed. 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)