# Allocate an item to many people

Allocates one item to a set of people in a single call. The work is queued
rather than done while you wait, so a 200 means the request was accepted, not
that anyone has been allocated anything yet.
**The token in the response cannot be looked up.** There is no endpoint that
resolves it and no completion callback, so confirm the outcome by listing the
item's allocations rather than by polling. Nothing is reported back if some
people could not be allocated - a person already holding as many as the item
permits, or an item that runs out of stock or serials part way through, is
skipped and the run continues.
Choose who to allocate to with applyTo: send `selected` together with the list
of person IDs, or any other value to allocate to everyone the caller can see,
narrowed by filter.
quantity is how many of the item each person gets, and it is honoured here -
the item is allocated that many times per person.
Note applyTo is camelCase, unlike every other field on this endpoint.

Endpoint: POST /api/v2/inventory/item/user/mass-add-item-to-users
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `inventory_item_id` (integer, required)
    The ID of the item to allocate. Required, and it must be an item the account can use.

  - `inventory_allocation_type` (string, required)
    How the people being allocated the item came by it - for example `rewards`. Recorded against each allocation and used in reporting.

  - `quantity` (integer, required)
    How many of the item each person gets. Required. Unlike the single-allocation endpoint, this figure is honoured: the item is allocated this many times to every person matched.

  - `applyTo` (string, required)
    Send `selected` to allocate to the people named in selected. Any other value allocates to every person the caller can see, narrowed by filter if one is sent.

  - `expires_at` (string)
    When the allocations stop being valid, as `YYYY-MM-DD HH:MM:SS`. Left unset, each allocation takes its expiry from the item's validity period if it has one. Applies to distributable items.

  - `collected_at` (string)
    When the item was handed over, as `YYYY-MM-DD HH:MM:SS`. Set it to record allocations that have already been collected. Applies to distributable items.

  - `selected` (array)
    The IDs of the people to allocate to. Required when applyTo is `selected`, and ignored otherwise.

  - `filter` (array)
    Narrows who the item is allocated to when applyTo is not `selected`, using the same filter syntax as the user listing.

## Response 200 fields (application/json):

  - `queue` (string)