563848e0ecc0
List roster jobs for the tenant
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
Upper-bound cursor: stop at the roster job with this identifier. Use an id from a previous response. Do not combine with page/size or startAfterId.
Filter criteria. The filter parameter must be URL encoded when sent.
Examples (before URL encoding):
-
- Filter by id: {"id":{"eq":"123"}} Example curl commands:
# Filter by id
curl -X GET '<BaseURL>/roster?filter=%7B%22id%22%3A%7B%22eq%22%3A%223%22%7D%7D'
Available filter operations:
- eq: Equal to
- neq: Not equal to
- gt: Greater than
- gte: Greater than or equal to
- lt: Less than
- lte: Less than or equal to
- in: Value must be one of these (array)
- nin: Value must not be any of these (array)
- contains: String contains (case-sensitive, string fields only)
Note: When using the filter parameter in a browser or code, make sure to properly URL encode the JSON string.
Zero-based page number for offset pagination. Do not combine with the cursor parameters.
Number of roster jobs per page. Defaults to 50.
Field to order by. Defaults to 'createdAt'.
Order direction: ASC or DESC. Defaults to 'DESC'.
Forward cursor: return jobs positioned after this identifier. Use the last id from the previous page to continue iterating. Do not combine with page/size or endAtId.
Headers
Unique identifier of the tenant that owns the roster jobs. Obtained from your account configuration; it scopes every roster this request can reach.
Response
A page of roster jobs for the tenant, ordered by the requested sort field.