# Allocate an item to a person Gives one unit of the item in the URL to one person and returns the allocation. **One record is one unit.** quantity is accepted but not stored, so send the request again to give someone several. If the item limits how many one person may hold, an allocation that would exceed the limit is **rejected** and reports the limit. Send ignore_max_per_user to allocate anyway. For an item with serials, the serial is taken care of according to how the item is set up - assigned automatically from the free pool, or expected to be named when the item is handed over. An item with no free serials left cannot be allocated. Leave collected_at unset for an allocation that has not been handed over yet; that is what the collect endpoint acts on. Leave expires_at unset to take the expiry from the item's validity period. The allocation comes back with the person and the item embedded, so a follow-up read is not needed. Endpoint: POST /api/v2/inventory/item/{item_id}/user Version: 2.0.0 Security: default ## Path parameters: - `item_id` (integer, required) The ID of the inventory item. ## Header parameters: - `Rosterfy-Platform` (string) ## Request fields (application/json): - `user_id` (integer, required) The ID of the person the item is allocated to. Required on create. - `inventory_allocation_type` (string) How the person came by the item - for example `rewards` when they redeemed it with points. Recorded against the allocation and used in reporting; it does not change how the allocation behaves. - `expires_at` (string) When the allocation stops being valid, as `YYYY-MM-DD HH:MM:SS`. Left unset on create, it is worked out from the item's validity period if it has one. - `collected_at` (string) When the person physically received the item, as `YYYY-MM-DD HH:MM:SS`. Leave unset for an allocation that has not been handed over yet; an allocation with no collection time is what the collect endpoint acts on. - `ignore_max_per_user` (boolean) Set to allocate the item even though the person already holds as many as the item permits. Without it, an allocation over that limit is rejected. Accepted on create only. - `quantity` (integer) Not stored. The allocation record holds one unit, so this field is accepted and then discarded - allocate the item more than once to give someone several. ## Response 201 fields (application/json): - `object` (object) - `object.id` (integer) - `object.inventory_allocation_id` (string | null) - `object.inventory_item_id` (integer) - `object.user_id` (integer) - `object.entity` (string | null) - `object.entity_id` (string | null) - `object.inventory_allocation_type` (string) - `object.serial` (string | null) - `object.inventory_item_serial_id` (string | null) - `object.expires_at` (string) - `object.collected_at` (string) - `object.collected_entity` (string | null) - `object.collected_by` (string | null) - `object.data` (string | null) - `object.sort_order` (integer) - `object.deleted_at` (string | null) - `object.created_at` (string) - `object.updated_at` (string) - `nice` (object) - `nice.inventory_allocation_type` (string) - `nice.user_name` (string) - `relations` (object) - `relations.user` (object) - `relations.user.object` (object) - `relations.user.object.id` (integer) - `relations.user.object.first_name` (string) - `relations.user.object.last_name` (string) - `relations.user.object.email` (string) - `relations.user.nice` (object) - `relations.user.nice.first_name` (string) - `relations.user.nice.last_name` (string) - `relations.user.permissions` (object) - `relations.user.permissions.read` (boolean) - `relations.user.permissions.update` (boolean) - `relations.user.permissions.delete` (boolean) - `relations.user.id` (integer) - `relations.user.name` (string) - `relations.inventory_allocation` (string | null) - `relations.inventory_item` (object) - `relations.inventory_item.object` (object) - `relations.inventory_item.object.id` (integer) - `relations.inventory_item.object.parent_id` (string | null) - `relations.inventory_item.object.type` (string) - `relations.inventory_item.object.external_id` (string) - `relations.inventory_item.object.certificate_id` (string | null) - `relations.inventory_item.object.is_image` (integer) - `relations.inventory_item.object.icon` (string) - `relations.inventory_item.object.variation_config` (string | null) - `relations.inventory_item.object.has_quantity` (integer) - `relations.inventory_item.object.quantity` (integer) - `relations.inventory_item.object.max_per_user` (integer) - `relations.inventory_item.object.has_serial` (integer) - `relations.inventory_item.object.category_id` (string | null) - `relations.inventory_item.object.serial_assignment_mode` (string | null) - `relations.inventory_item.object.is_distributable` (integer) - `relations.inventory_item.object.is_redeemable` (integer) - `relations.inventory_item.object.ttl` (string | null) - `relations.inventory_item.object.reward_point_cost` (integer) - `relations.inventory_item.object.budget_cost` (string) - `relations.inventory_item.object.publish` (integer) - `relations.inventory_item.object.sort_order` (integer) - `relations.inventory_item.object.has_variants` (integer) - `relations.inventory_item.object.varied_by_attribute_id` (string | null) - `relations.inventory_item.object.variant_source_id` (string | null) - `relations.inventory_item.object.is_archived` (integer) - `relations.inventory_item.object.is_distributable_at_checkin_checkout` (string | null) - `relations.inventory_item.object.deleted_at` (string | null) - `relations.inventory_item.object.is_erased` (integer) - `relations.inventory_item.object.created_at` (string) - `relations.inventory_item.object.updated_at` (string) - `relations.inventory_item.object.deleted_by` (string | null) - `relations.inventory_item.object.is_inheritable` (integer) - `relations.inventory_item.object.name` (string) - `relations.inventory_item.nice` (object) - `relations.inventory_item.nice.created_at` (string) - `relations.inventory_item.nice.created_at__date` (string) - `relations.inventory_item.nice.created_at__time` (string) - `relations.inventory_item.nice.created_at__offset` (string) - `relations.inventory_item.nice.created_at__offset_minutes` (integer) - `relations.inventory_item.nice.created_at__dayofweek` (string) - `relations.inventory_item.nice.external_id` (string) - `relations.inventory_item.nice.has_quantity` (string) - `relations.inventory_item.nice.has_variants` (string) - `relations.inventory_item.nice.is_distributable_at_checkin_checkout` (string) - `relations.inventory_item.nice.name` (string) - `relations.inventory_item.nice.publish` (string) - `relations.inventory_item.nice.type` (string) - `relations.inventory_item.nice.type:value` (string) - `relations.inventory_item.nice.type:array` (string) - `relations.inventory_item.nice.updated_at` (string) - `relations.inventory_item.nice.updated_at__date` (string) - `relations.inventory_item.nice.updated_at__time` (string) - `relations.inventory_item.nice.updated_at__offset` (string) - `relations.inventory_item.nice.updated_at__offset_minutes` (integer) - `relations.inventory_item.nice.updated_at__dayofweek` (string) - `relations.inventory_item.nice.distributed` (integer) - `relations.inventory_item.nice.allocated` (integer) - `relations.inventory_item.nice.available` (integer) - `relations.inventory_item.nice.stock_level` (string) - `relations.inventory_item.nice.manual_serial_required` (boolean) - `relations.inventory_item.nice.account_name_path` (string) - `relations.inventory_item.nice.is_foreign_account` (boolean) - `relations.inventory_item.permissions` (object) - `relations.inventory_item.permissions.read` (boolean) - `relations.inventory_item.permissions.update` (boolean) - `relations.inventory_item.permissions.delete` (boolean) - `relations.serial_obj` (string | null) - `permissions` (object) - `permissions.read` (boolean) - `permissions.update` (boolean) - `permissions.delete` (boolean) - `permissions.user_update` (boolean)