# Create an allocation rule

Sets up a rule that hands items out on its own: it names a thing to measure -
shifts worked, events attended, hours attended - and a threshold, and everyone
who reaches that threshold is given the items attached to the rule. Attach those
items with the create endpoint on the rule's own item list; a rule with no items
is valid and does nothing.
The rule is applied as people work, not retrospectively, so it takes effect from
the moment it is created rather than granting items to anyone who already meets
the threshold.
**The created rule comes back with only the fields that were set on it**, not
the full record that reading it returns, and without the item list. Read the
rule back if you need its complete state.

Endpoint: POST /api/v2/inventory/allocation
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `name` (string, required)
    A name for the allocation rule, used wherever it is listed.

  - `type` (string, required)
    What the people who qualify are being given. `entitlements` for something they have earned, `rewards` for something granted as a reward, and `redemption` for something exchanged for points. The value is recorded on every allocation the rule creates and is used in reporting. Send one of the three: other values are accepted here but stop the rule allocating anything when it next runs.

  - `rules` (array, required)
    The qualifying condition, as a list holding exactly one entry of the form `{"type": "<measure>", "value": <threshold>}`. `type` is the measure to count and `value` is the number the person has to reach. The measures are `total_number_of_shifts`, `total_number_of_events`, `total_shift_hours` (counted from scheduled times), `total_shift_hours_attended` (counted from check-in to check-out) and `shift_hours_per_day`. Required - and note that anything else, including an empty list, more than one entry, an unrecognised measure or a missing threshold, is rejected with a message saying the field is required rather than one describing what was wrong.

  - `conditions` (array)
    An optional list of further conditions narrowing who the rule applies to, on top of the measure in `rules`. The structure is not currently validated and is not part of this contract - build it in the console rather than by hand, and send back what you were given if you are updating a rule that already has one.

## Response 201 fields (application/json):

  - `object` (object)

  - `object.rules` (array)

  - `object.rules.type` (string)

  - `object.rules.value` (integer)

  - `object.conditions` (array)

  - `object.type` (string)

  - `object.name` (string)

  - `object.updated_at` (string)

  - `object.created_at` (string)

  - `object.id` (integer)

  - `nice` (object)

  - `nice.rule_name` (string)

  - `nice.rule_value` (integer)

  - `relations` (array)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)