# Roster people onto shifts

Fills a set of an event's shifts from a pool of people - a user group, the
accepted applicants of a role offer, or an uploaded file - creating a shift
application for each person placed.
**This write is queued, and the response carries no way to follow it.** A 200
means the request passed validation and the work was handed off, nothing more.
The body is a fixed confirmation message with no identifier in it, so there is
no request to poll and no way to be told when the rostering has finished or
what it did. Confirm the outcome by listing the event's shift applications and
looking for the new rows. Do not treat the response as meaning anyone has been
rostered.
Choose the shifts either way round:
- Send `applyTo` as `selected` with `selected` holding the shift IDs to fill.
- Send any other `applyTo` value to fill every shift on the event the caller can
see, narrowed by an optional `filter`.

Then choose the people with `source`, and supply whichever field that source
needs: `group_id` for `group`, `role_offer_id` for `role_offer`, `file` for
`import`. A `source` that is none of those three is accepted and rosters nobody.
How many people go onto each shift is decided by that shift's own demand, so a
shift that is already full takes nobody. Running the same request twice is
therefore close to safe, though it will consider the same people again unless
`bypass_scheduled` is set.
Invalid input returns a 422 before anything is queued.
Note that `applyTo` is spelled in camelCase, unlike every other parameter on
this endpoint.

Endpoint: PUT /api/v2/automatic-rostering/event-shift
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `event_id` (integer, required)
    The event whose shifts are to be filled. Required in practice - a request without it is accepted and then rosters nobody.

  - `group_id` (integer)
    The user group to roster from. Required when source is `group`.

  - `headcount_functional_area_id` (array)
    Limits rostering to shifts in these functional areas. Applies when source is `role_offer` and specific_role is not set.

  - `role_offer_id` (integer)
    The role offer whose accepted applicants are rostered. Used when source is `role_offer`. Leave it out to roster each shift from whichever role offer that shift is already tied to.

  - `specific_role` (boolean)
    Send `1` with source `role_offer` to roster only the role offer named in role_offer_id, rather than matching each shift to its own role offer.

  - `event_shift_status_id` (integer, required)
    The status each new shift application is created with, from the event_shift_status option set. This is what decides whether the people rostered are placed as confirmed, pending approval, or something else.

  - `applyTo` (string, required)
    Send `selected` to fill only the shifts named in selected. Any other value fills every shift on the event that the caller can see, narrowed by filter if one is sent.

  - `selected` (array)
    The IDs of the shifts to fill. Read when applyTo is `selected`, and ignored otherwise.

  - `bypass_scheduled` (boolean)
    Send `1` to skip anyone already rostered onto the shifts in scope, so a repeated request does not consider them again.

  - `source` (string, required)
    Where the people come from: `group` to use a user group, `role_offer` to use the accepted applicants of a role offer, or `import` to upload a file of them. Any other value is accepted and rosters nobody.

  - `filter` (array)
    Narrows which of the event's shifts are filled, in the same form the shift listing accepts. Read only when applyTo is not `selected`.

  - `file` (string)
    The file of people to roster, as a multipart upload. Required when source is `import`, rejected as an unsupported format otherwise. Accepts the same spreadsheet and CSV formats as an import.

## Response 200 fields (application/json):

  - `message` (string)