# Add a user to a role offer

Creates an application for one person against the role offer in the URL, at the
status you name, and returns it.
The created record carries only the fields the create set - the rest of an
application's fields are filled in as it progresses - so read it back if you
need the full shape.
A person can hold only one live application per role offer. A second one comes
back as a **422** naming `user_id`; delete the existing application first if you
mean to start over.
**Three business rules can refuse an otherwise valid create, each with a `403`
and a message saying which:**
- the role offer has no places left at that status, either on its main demand,
its waitlist, its reserve list or its secondary allowance;
- the person already holds as many roles as the account permits;
- the account does not allow an application to start at that status.

**A fourth returns a `405`**, because it is a limit an authorised caller may
choose to pass: adding this person would take the role offer past its confidence
level. The body carries a `reference`, and a caller holding the matching
permission can repeat the request with that key in an `override` **query
parameter** - `?override[]=headcount.roleoffer.confidence_level` - to go ahead.
Sending `override` in the JSON body does not work.
Beyond the fields listed here the endpoint also accepts the account's own
configured attributes for an application. Invalid input returns a 422 naming the
fields at fault.

Endpoint: POST /api/v2/headcount/roleoffer/{roleoffer_id}/user
Version: 2.0.0
Security: default

## Path parameters:

  - `roleoffer_id` (integer, required)
    The ID of the role offer.

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `status_id` (integer, required)
    Where the application stands. Read the available statuses, and the id of each, from the status option set - they are configured per account, so do not hard-code ids. Changing this is the main thing an update does, and it is what sets off whatever the account has configured to follow a status change. An account may also restrict which statuses can follow which, in which case a move it does not allow is refused.

  - `user_id` (integer, required)
    The user to add to the role offer. A user can hold only one live application per role offer; a second one is rejected. Cannot be changed afterwards - to move someone to a different role offer, delete this application and create another.

  - `secondary_assignment` (boolean)
    Mark the application as a secondary one. Secondary applications do not count towards the limit on how many roles a person may hold, and are counted against the role offer's separate secondary allowance rather than its main demand.

  - `is_reserved` (boolean)
    Place the person in the role offer's reserve list, taking up one of its reserved places rather than one of its main ones. Only meaningful on a role offer that has reserved places configured; on one that does not, the request is refused because the reserve list has no room.

  - `custom_*` (string)
    A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation.

## Response 201 fields (application/json):

  - `object` (object)

  - `object.id` (integer)

  - `object.role_offer_id` (integer)

  - `object.user_id` (integer)

  - `object.status_id` (integer)

  - `object.status_update_at` (string)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `nice` (object)

  - `nice.rrn` (string)

  - `nice.journey_step` (string)

  - `nice.journey_step_category` (string)

  - `nice.created_at` (string)

  - `nice.created_at__date` (string)

  - `nice.created_at__time` (string)

  - `nice.created_at__offset` (string)

  - `nice.created_at__offset_minutes` (integer)

  - `nice.created_at__dayofweek` (string)

  - `nice.feedback` (string)

  - `nice.status_id` (string)

  - `nice.status_id:value` (integer)

  - `nice.status_id:array` (string)

  - `nice.status_update_at` (string)

  - `nice.status_update_at__date` (string)

  - `nice.status_update_at__time` (string)

  - `nice.status_update_at__offset` (string)

  - `nice.status_update_at__offset_minutes` (integer)

  - `nice.status_update_at__dayofweek` (string)

  - `nice.updated_at` (string)

  - `nice.updated_at__date` (string)

  - `nice.updated_at__time` (string)

  - `nice.updated_at__offset` (string)

  - `nice.updated_at__offset_minutes` (integer)

  - `nice.updated_at__dayofweek` (string)

  - `nice.status` (string)

  - `nice.status_is_public` (boolean)

  - `nice.status_type` (string)

  - `nice.user_name` (string)

  - `nice.has_received_invitation` (boolean)

  - `nice.status_color` (string)

  - `nice.status_lightness` (integer)

  - `relations` (object)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)

  - `permissions.status_update` (boolean)

  - `permissions.downloadCertificate` (boolean)

## Response 403 fields (application/json):

  - `message` (string)

## Response 405 fields (application/json):

  - `message` (string)

  - `reference` (string)