Retrieve a roster job with a file download link

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.