# Update a role offer

Updates a role offer and returns it in the same shape as reading one. Every field
is optional; only the fields sent are changed, with the exceptions below.
The account's own attribute configuration takes precedence over the fields listed
below, exactly as it does on create.
Four fields are reset rather than left alone when their enabling field is absent
from the request. Send expires_in_enable alongside expires_in to keep it,
enable_waitlist alongside waitlist_demand and waitlist_auto_invitation_enabled,
and has_age_limit alongside minimum_dob and minimum_age. Omitting the enabling
field clears the value it guards. Omitting rules clears the role offer's rules.
Where the role offer was created from a template, values the template locks are
dropped from the request and the update still returns a 200. A locked field can
only be changed by sending {field}:override=1 next to it, and only by a caller
allowed to override template-locked fields. The journey a role offer belongs to
can never be changed after creation.
Invalid input returns a 422 identifying the fields at fault. Reducing demand below
what is already filled, exceeding the account's confidence level, or removing a
payment requirement that applications depend on are all reported this way.

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

## Path parameters:

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

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `headcount_functional_area_job_title_id` (integer)
    The job title being recruited for. A role offer is unique on the combination of job title and venue.

  - `headcount_location_venue_id` (integer)
    The venue the role is worked at. A role offer is unique on the combination of job title and venue.

  - `user_type_id` (integer)
    The type of person the role is offered to, which governs how many shifts one of them can be rostered onto.

  - `static_demand` (integer)
    The number of people needed. Use this when demand is set directly; it is ignored when calculate_demand is 1.

  - `min_demand` (integer)
    The minimum number of accepted people the role needs to be considered viable. Used for reporting; it does not stop applications.

  - `calculate_demand` (boolean)
    Set to 1 to derive demand from the shift pattern instead of setting it directly, in which case user_per_shift, number_of_shifts_per_day, start_date and end_date are used and static_demand is ignored. Defaults to 0.

  - `waitlist_demand` (integer)
    How many people may join a waitlist once the role is full. Send enable_waitlist alongside it on update, or the waitlist is switched off.

  - `waitlist_auto_invitation_enabled` (boolean)
    Set to 1 to invite waitlisted people to apply automatically as places free up. Ignored unless waitlist_demand is set.

  - `user_per_shift` (integer)
    How many people each shift needs. Only used when calculate_demand is 1.

  - `peak_shift` (integer)
    The largest number of concurrent shifts to plan for. Only used when calculate_demand is 1.

  - `number_of_shifts_per_day` (integer)
    How many shifts run per day. Only used when calculate_demand is 1.

  - `start_date` (string)
    First day demand is calculated across, as YYYY-MM-DD. Only used when calculate_demand is 1.

  - `end_date` (string)
    Last day demand is calculated across, as YYYY-MM-DD. Must not be before start_date. Only used when calculate_demand is 1.

  - `role_feedback_form_id` (integer)
    A form the person is offered on their dashboard once the role is complete.

  - `publish` (boolean)
    Set to 1 to make the role offer live. An unpublished role offer is not visible to applicants.

  - `promoted` (boolean)
    Set to 1 to feature the role on the portal dashboard.

  - `secondary_assignment_demand` (integer)
    How many people may take the role as a second assignment, which does not count towards the number of roles they hold. Cannot exceed the role's demand, and is ignored when calculate_demand is 1.

  - `confidence_level` (integer)
    How far over demand the role may be filled, as a percentage between 0 and 100, to allow for people dropping out.

  - `rules` (array)
    Conditions that govern who may apply and what applying costs. Omitting this on update clears the role's existing rules. A rule missing a required part is dropped rather than rejected, so the role can come back with fewer rules than were sent.

  - `ranking` (array)
    Ranking bands used to order applicants. Update only.

  - `sort_order` (integer)
    Position of the role in listings. Lower sorts first.

  - `expires_in` (integer)
    How many days an unanswered offer stays open before it expires. Send expires_in_enable alongside it, or expiry is switched off and this resets to 0.

  - `certificate_id` (integer)
    A certificate awarded once someone completes the role.

  - `accept_form_id` (integer)
    A form shown when someone accepts the role.

  - `reject_form_id` (integer)
    A form shown when someone rejects the role.

  - `training_ids` (array)
    Training modules assigned to everyone who takes the role.

  - `is_archived` (string)
    Set to 1 to archive the role offer, hiding it from the default listing without deleting it. Update only.

  - `preassign_enabled` (boolean)
    Set to 1 to allow people to be pre-assigned to the role before applications open.

  - `banner_image` (string)
    Banner shown at the top of the role's page. Either an uploaded image or the URL of one.

  - `grid_image` (string)
    Thumbnail shown wherever the role appears in a grid listing. Either an uploaded image or the URL of one.

  - `public` (boolean)
    Set to 1 to make the role visible without signing in, on the public listing.

  - `can_self_apply` (boolean)
    Set to 1 to let people apply themselves rather than having the role assigned to them. Setting it to 0 clears the role's tags.

  - `timezone` (string)
    The timezone the role's dates and times are interpreted in. Defaults to the account's timezone.

  - `apps_open_timestamp` (string)
    When applications open, as YYYY-MM-DD HH:MM:SS. Nobody can apply before it.

  - `apps_close_timestamp` (string)
    When applications close, as YYYY-MM-DD HH:MM:SS. Nobody can apply after it, and it must be later than apps_open_timestamp.

  - `minimum_dob` (string)
    The latest date of birth allowed, as YYYY-MM-DD. Someone born after it cannot apply from the portal. Cannot be combined with minimum_age.

  - `minimum_age` (string)
    The youngest age allowed, as years and months separated by a colon, for example "18:0". Cannot be combined with minimum_dob.

  - `maximum_dob` (string)
    The earliest date of birth allowed, as YYYY-MM-DD. Someone born before it cannot apply from the portal.

  - `maximum_age` (string)
    The oldest age allowed, as years and months separated by a colon, for example "65:0".

  - `applied_status_default` (integer)
    The status given to someone when they apply for the role. Defaults to the account's applied status.

  - `withdrawn_status_default` (integer)
    The status given to someone when they withdraw from the role. Defaults to the account's withdrawn status.

  - `application_form_id` (integer)
    A form that must be completed before applying for the role.

  - `approval_status` (string)
    Where the role offer sits in the approval process. On an account that requires approval, a caller who cannot approve may only submit it for approval. Update only.

  - `approval_reason` (string)
    Note recorded against the current approval decision. Update only.

  - `allows_application_withdrawals` (boolean)
    Set to 1 to let people withdraw after applying. Switched off automatically for a role that is neither part of a journey nor self-apply.

  - `withdraw_form_id` (string)
    A form that must be completed before withdrawing from the role.

  - `payment` (object)
    What applying to the role costs, and how it is charged.

  - `is_refund_allowed` (boolean)
    Set to 1 to permit refunds of an application fee for this role.

  - `withdraw_close_timestamp` (string)
    After this point people can no longer withdraw, as YYYY-MM-DD HH:MM:SS.

  - `refund_on_application_withdraw` (boolean)
    Set to 1 to refund the application fee automatically when someone withdraws.

  - `refund_on_role_offer_complete` (boolean)
    Set to 1 to refund the application fee automatically once the role is complete.

  - `strict_applications_enabled` (boolean)
    Set to 1 to stop accepting applications once demand is met.

  - `reserve_demand` (integer)
    How many of the places are held back rather than opened to applicants. Cannot exceed static_demand.

  - `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.headcount_functional_area_job_title_id` (integer)

  - `object.headcount_location_venue_id` (integer)

  - `object.journey_id` (string | null)

  - `object.role_offer_template_id` (string | null)

  - `object.user_type_id` (integer)

  - `object.certificate_id` (string | null)

  - `object.static_demand` (integer)

  - `object.reserve_demand` (integer)

  - `object.waitlist_demand` (integer)

  - `object.confidence_level` (integer)

  - `object.calculate_demand` (integer)

  - `object.refund_on_application_withdraw` (integer)

  - `object.refund_on_role_offer_complete` (integer)

  - `object.user_per_shift` (integer)

  - `object.peak_shift` (integer)

  - `object.min_demand` (integer)

  - `object.number_of_shifts_per_day` (integer)

  - `object.min_number_shift_users` (integer)

  - `object.max_number_shift_users` (integer)

  - `object.start_date` (string | null)

  - `object.end_date` (string | null)

  - `object.role_feedback_form_id` (string | null)

  - `object.secondary_assignment_demand` (integer)

  - `object.rules` (array)

  - `object.ranking` (string | null)

  - `object.expires_in` (integer)

  - `object.preassign_enabled` (integer)

  - `object.sort_order` (integer)

  - `object.accept_form_id` (string | null)

  - `object.reject_form_id` (string | null)

  - `object.training_ids` (array)

  - `object.payment` (string | null)

  - `object.publish` (integer)

  - `object.promoted` (integer)

  - `object.is_archived` (integer)

  - `object.is_refund_allowed` (integer)

  - `object.created_by` (string | null)

  - `object.grid_image` (string | null)

  - `object.banner_image` (string | null)

  - `object.public` (integer)

  - `object.approval_status` (string)

  - `object.approval_reason` (string | null)

  - `object.visibility_show_groups` (array)

  - `object.visibility_hide_groups` (array)

  - `object.can_self_apply` (integer)

  - `object.application_form_id` (string | null)

  - `object.withdraw_form_id` (string | null)

  - `object.allows_application_withdrawals` (integer)

  - `object.timezone` (string | null)

  - `object.apps_open_timestamp` (string | null)

  - `object.apps_close_timestamp` (string | null)

  - `object.withdraw_close_timestamp` (string | null)

  - `object.minimum_dob` (string | null)

  - `object.minimum_age` (string | null)

  - `object.maximum_dob` (string | null)

  - `object.maximum_age` (string | null)

  - `object.applied_status_default` (string | null)

  - `object.withdrawn_status_default` (string | null)

  - `object.journey_complete_status_default` (string | null)

  - `object.deleted_at` (string | null)

  - `object.is_erased` (integer)

  - `object.strict_applications_enabled` (integer)

  - `object.waitlist_auto_invitation_enabled` (integer)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `object.deleted_by` (string | null)

  - `object.description` (string)

  - `object.tags` (string | null)

  - `nice` (object)

  - `nice.rrn` (string)

  - `nice.accept_form_id` (string | null)

  - `nice.accept_form_id:value` (string | null)

  - `nice.accept_form_id:array` (string | null)

  - `nice.allows_application_withdrawals` (string)

  - `nice.application_form_id` (string | null)

  - `nice.application_form_id:value` (string | null)

  - `nice.application_form_id:array` (string | null)

  - `nice.applied_status_default` (string | null)

  - `nice.applied_status_default:value` (string | null)

  - `nice.applied_status_default:array` (string | null)

  - `nice.approval_status` (string)

  - `nice.approval_status:value` (string)

  - `nice.approval_status:array` (string)

  - `nice.banner_image` (string)

  - `nice.calculate_demand` (string)

  - `nice.can_self_apply` (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_form_id` (string | null)

  - `nice.feedback_form_id:value` (string | null)

  - `nice.feedback_form_id:array` (string | null)

  - `nice.grid_image` (string)

  - `nice.headcount_functional_area_job_title_id` (string)

  - `nice.headcount_functional_area_job_title_id:value` (integer)

  - `nice.headcount_functional_area_job_title_id:array` (string)

  - `nice.headcount_location_venue_id` (string)

  - `nice.headcount_location_venue_id:value` (integer)

  - `nice.headcount_location_venue_id:array` (string)

  - `nice.is_refund_allowed` (string)

  - `nice.journey_complete_status_default` (string | null)

  - `nice.journey_complete_status_default:value` (string | null)

  - `nice.journey_complete_status_default:array` (string | null)

  - `nice.journey_id` (string | null)

  - `nice.journey_id:value` (string | null)

  - `nice.journey_id:array` (string | null)

  - `nice.minimum_age` (string)

  - `nice.preassign_enabled` (string)

  - `nice.promoted` (string)

  - `nice.public` (string)

  - `nice.publish` (string)

  - `nice.reject_form_id` (string | null)

  - `nice.reject_form_id:value` (string | null)

  - `nice.reject_form_id:array` (string | null)

  - `nice.tags` (string | null)

  - `nice.tags:value` (string | null)

  - `nice.tags:array` (string | null)

  - `nice.training_ids` (string)

  - `nice.training_ids:value` (string)

  - `nice.training_ids:array` (array)

  - `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.user_type_id` (string)

  - `nice.user_type_id:value` (integer)

  - `nice.user_type_id:array` (string)

  - `nice.visibility_hide_groups` (string)

  - `nice.visibility_show_groups` (string)

  - `nice.withdraw_form_id` (string | null)

  - `nice.withdraw_form_id:value` (string | null)

  - `nice.withdraw_form_id:array` (string | null)

  - `nice.withdrawn_status_default` (string | null)

  - `nice.withdrawn_status_default:value` (string | null)

  - `nice.withdrawn_status_default:array` (string | null)

  - `nice.account_id` (integer)

  - `nice.account_url` (string)

  - `nice.confidence_level` (string)

  - `relations` (array)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)

  - `permissions.accept` (boolean)

  - `permissions.reject` (boolean)

  - `permissions.withdraw` (boolean)

  - `permissions.apply` (boolean)

  - `permissions.apply_error` (string)

  - `permissions.apply_error_code` (integer)

  - `permissions.update_application_form` (boolean)