# Update an application

Moves an application to a new status, and optionally records a note or changes
whether it is a secondary or a reserved place. Returns the application in the
same shape as reading it.
**`status_id` is required on every update**, so unlike most updates in this API
an empty body is a 422 rather than a no-op. Send the status the application
should now be at, even if it is the one it is already at. If you do not know the
account's status ids, send `status_type` instead and the matching status is
resolved for you.
Changing the status is what sets off everything the account has configured to
follow it - emails, journey steps, certificates. It is also the point at which
the same limits the create is subject to are re-checked, so an update can come
back as a **403** naming the demand, allowance or transition rule that refused
it, or a **405** for the confidence level - see the create for how to pass that
one.
Two behaviours worth knowing:
- Moving an application off a waitlist reorders the rest of that waitlist, so
other applications on the same role offer change as a side effect of this one.
- Where the account withdraws people from future shifts when they leave a role,
moving an application to a status that counts as declined does that too.

`user_id` and `role_offer_id` are accepted and ignored: an application cannot be
moved to another person or another role offer. Beyond the fields listed here the
endpoint also accepts the account's own configured attributes for an
application.

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

## Path parameters:

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

  - `id` (integer, required)
    The ID of the application.

## 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.

  - `feedback` (string)
    Free-text note recorded against the application. Not shown to the person the application belongs to.

  - `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.

  - `status_type` (string)
    An alternative to `status_id` on update: send the type of the status you want - for example `accepted` or `declined` - and it is resolved to the matching status for the account. Use it when you know the outcome you want but not the account's ids. A type that matches nothing is not reported as such; the request comes back as a 422 naming `status_id` instead.

  - `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 200 fields (application/json):

  - `object` (object)

  - `object.id` (integer)

  - `object.role_offer_id` (integer)

  - `object.user_id` (integer)

  - `object.status_id` (integer)

  - `object.ranking` (integer)

  - `object.role_offer_feedback_form_completed_at` (string | null)

  - `object.secondary_assignment` (integer)

  - `object.expires_at` (string | null)

  - `object.feedback` (string | null)

  - `object.status_update_at` (string)

  - `object.application_form_completed_at` (string)

  - `object.application_withdrawn_at` (string | null)

  - `object.sort_order` (integer)

  - `object.waitlist_invitation_email_sent_at` (string | null)

  - `object.waitlist_reminder_email_sent_at` (string | null)

  - `object.is_reserved` (integer)

  - `object.deleted_at` (string | null)

  - `object.is_erased` (integer)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `object.deleted_by` (string | null)

  - `nice` (object)

  - `nice.rrn` (string)

  - `nice.journey_step` (string)

  - `nice.journey_step_category` (string | null)

  - `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)