# Create a role offer

Creates a role offer and returns it in the same shape as reading one, so a
follow-up read is not needed. A role offer is unique on the combination of job
title and venue; reusing a pair that already has one is refused.
The account's own attribute configuration takes precedence over the fields
listed below. Where an attribute is configured for role offers, its definition
replaces the rule documented here, which can change both the accepted format and
whether the field is required. The presence flags below reflect what the endpoint
actually enforces on a default configuration.
Supplying role_offer_template_id copies the template's values over anything sent
alongside it, so a templated create ignores most of the body. A field can only be
kept by sending {field}:override=1 next to it, and only by a caller allowed to
override template-locked fields.
Demand is expressed one of two ways. With calculate_demand unset or 0, set
static_demand to the number of people needed. With calculate_demand=1, demand is
derived from user_per_shift, number_of_shifts_per_day, start_date and end_date
instead.
Invalid input returns a 422 identifying the fields at fault. Sending both
minimum_dob and minimum_age is rejected, as they are two ways to say one thing.

Endpoint: POST /api/v2/headcount/roleoffer
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

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

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

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

  - `role_offer_template_id` (integer)
    A template to build the role offer from. The template's values are copied over anything sent alongside it, so most other fields are ignored when this is set. Create only.

  - `description` (string)
    Description of the role, shown to applicants in the portal. Accepts HTML.

  - `static_demand` (integer, required)
    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.

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

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

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

  - `publish` (boolean, required)
    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.

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

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

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

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

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