Submit a roster file for import

Uploads a roster file and opens a new import job for it.

When to use: call this to start a fresh import cycle; to replace the file on a job that already exists, use PUT /roster/{rosterId}/reupload instead.

Preconditions: send a multipart request carrying the file part and the tenant-id header. jobType must be one of PRACTITIONER, FACILITY, or GROUP (GROUP additionally requires the tenant's supportGroupRosters configuration), and a roster template matching that job type must already exist for the tenant - if it does not, the request fails with 404. Accepted file formats are CSV, XLSX, TSV, JSON, and TXT; when the file is an .xlsx, sheetName names the worksheet to read. templateId is always required and references the saved column layout; mappings may additionally supply column mappings inline as a JSON string.

What you get back: 201 with the newly created roster job at its starting status. Take the job's id from the response and poll GET /roster/{id} to follow progress.

Side effects: the uploaded file is stored and a validation run is queued - except for .txt uploads, which are held at PRE_PROCESSING for pre-processing first, so read the returned status rather than assuming validation has begun. A notification email is sent for interactively uploaded rosters (automated feeds notify through their own configured recipients, and tenants may be excluded from these emails by configuration). Not idempotent - every call creates another roster job, so re-submitting the same file produces a duplicate import. The job's data object carries its status, file details, and record counters; see GET /roster/{id} for the full list of keys it can hold.