# Create an event

Creates an event in the account you are calling as. The response is the same shape
as reading the event back, so a follow-up read is not needed.
**Only `name` and `description` have to be sent.** Everything the rules below mark
required beyond those two is filled in from the account's own defaults before the
request is validated - the timezone, the five shift status defaults, the
publication status - and the event type falls back to the first one the account
has. New events are created unpublished.
**An event needs a location.** Send an `address`, or a
`headcount_location_venue_id`, or set `is_virtual`. A request with none of the
three is rejected even though each of them is individually optional.
Send `event_template_id` to build the event from one of the account's templates.
The template's values are applied over the rest of the request, so a field the
template sets wins over the one you send.
Where the account has attribute prefilling turned on, fields you leave out may
come back with values of their own, taken from the defaults configured for your
role. Read the response rather than assuming an omitted field is empty.
The account's own configured attributes are accepted as `custom_*` fields.

Endpoint: POST /api/v2/event
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `event_template_id` (integer)
    The template to build the event from. Its values are applied over whatever else you send. Send `no_template` to start from nothing instead. Where the account has templates configured, one of the two is expected.

  - `name` (string, required)
    What the event is called. Shown to everyone who can see the event.

  - `event_type_id` (integer)
    Which of the account's event types this is. Defaults to the account's first type when left out.

  - `description` (string, required)
    The event's description, as HTML. Shown on the event's page in the portal.

  - `timezone` (string)
    The timezone every timestamp on the event is given in, as an IANA name such as `Australia/Melbourne`. Defaults to the account's timezone.

  - `start_timestamp` (string)
    When the event starts, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Required when the event is not ongoing. Cleared if you mark the event ongoing.

  - `end_timestamp` (string)
    When the event ends, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Defaults to the start when the event is not ongoing. Cleared if you mark the event ongoing.

  - `is_virtual` (boolean)
    Whether the event has no physical location. A virtual event needs neither an address nor a venue.

  - `shift_status_default` (integer)
    The status a new application to a shift on this event starts in. Defaults to the account's.

  - `shift_confirmed_status_default` (integer)
    The status applied when someone confirms their place on a shift. Defaults to the account's.

  - `shift_rejected_status_default` (integer)
    The status applied when someone is turned down for a shift. Defaults to the account's.

  - `shift_can_withdraw_default` (boolean)
    Whether people may withdraw from this event's shifts.

  - `shift_can_confirm_default` (boolean)
    Whether people are asked to confirm their place on this event's shifts.

  - `shift_can_withdraw_limit` (integer)
    How long before a shift starts withdrawing stops being allowed, in seconds.

  - `shift_can_confirm_limit` (integer)
    How long before a shift starts confirming stops being allowed, in seconds.

  - `shift_checked_in_status_default` (integer)
    The status applied when someone checks in to a shift. Defaults to the account's.

  - `shift_checked_out_status_default` (integer)
    The status applied when someone checks out of a shift. Defaults to the account's.

  - `apps_open_timestamp` (string)
    When applications open, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Leave empty for applications that are open from the start.

  - `apps_close_timestamp` (string)
    When applications close, as `YYYY-MM-DD HH:MM:SS` in the event's timezone. Must be after `apps_open_timestamp`.

  - `max_shift_apps_per_user` (integer)
    The most shifts on this event one person may hold. `0` means no limit.

  - `min_shift_apps_per_user` (integer)
    The fewest shifts on this event one person is expected to hold. `0` means no minimum.

  - `min_shift_apps_per_shift_type` (object)
    Per-shift-type minimums, as an object keyed by shift type id.

  - `max_shift_apps_per_shift_type` (object)
    Per-shift-type ceilings, as an object keyed by shift type id.

  - `gap_between_shifts` (integer)
    The rest required between two shifts on this event, in seconds. `0` means none.

  - `role_offer_address` (boolean)
    Whether the event takes its location from the role offer people applied through rather than from its own address.

  - `status` (string)
    Whether the event is visible to people who can apply: `published`, `unpublished`, `auto_publish`, `submit_for_approval` or `rejected`. New events start unpublished.

  - `parent_id` (integer)
    The id of the event this one sits beneath, for accounts that group events into a parent and its sub-events.

  - `address` (object)
    Where the event takes place. Required unless the event is virtual or is held at a venue.

  - `headcount_location_venue_id` (integer)
    The venue the event is held at, instead of an address of its own.

  - `headcount_functional_area_job_title_id` (integer)
    The job title this event's work is counted against for workforce planning.

  - `certificate_id` (integer)
    The certificate awarded for taking part in this event.

  - `visibility_show_groups` (array)
    Restrict the event to these groups, as a list of group ids. An empty list shows it to everyone.

  - `visibility_hide_groups` (array)
    Hide the event from these groups, as a list of group ids.

  - `visibility_show_roleoffer` (array)
    Restrict the event to people who came through these role offers, as a list of role offer ids.

  - `shift_application_form_id_default` (integer)
    The form filled in when applying for one of this event's shifts.

  - `shift_precheckin_form_id_default` (integer)
    The form filled in before checking in to one of this event's shifts.

  - `shift_checkin_form_id_default` (integer)
    The form filled in at check-in.

  - `shift_attended_form_id_default` (integer)
    The form filled in once attendance is recorded.

  - `shift_checkout_form_id_default` (integer)
    The form filled in at check-out.

  - `shift_feedback_form_id_default` (integer)
    The feedback form offered after one of this event's shifts.

  - `shift_leader_feedback_form_id_default` (integer)
    The feedback form a shift leader is asked to fill in.

  - `shift_precheckin_open_default` (integer)
    How long before a shift starts its pre-check-in form becomes available, in seconds.

  - `max_group_demand_default` (integer)
    The most places a group leader may reserve on one of this event's shifts.

  - `group_booking_ttl_default` (integer)
    How long a group leader's reserved places are held before they are released, in seconds.

  - `geofence_checkin_limit_default` (integer)
    How close to the shift's location someone must be to check in, in metres. Empty means no limit.

  - `self_checkin` (boolean)
    Whether people may check themselves in to this event's shifts.

  - `self_checkin_open` (integer)
    How long before a shift starts self check-in opens, in seconds.

  - `self_checkin_close` (integer)
    How long after a shift starts self check-in closes, in seconds.

  - `self_checkout_close` (integer)
    How long after a shift ends self check-out closes, in seconds.

  - `checkin_close_default` (integer)
    How long after a shift ends check-in closes, in seconds.

  - `checkin_visible_attributes` (array)
    Which fields are shown on the check-in page, as a list of `<entity>.<attribute>` names such as `user.first_name`.

  - `shift_filter_attributes` (array)
    Which attributes people may filter this event's shifts by, as a list of attribute ids.

  - `leader_shift_filter_attributes` (array)
    Which attributes a shift leader may filter by, as a list of attribute ids.

  - `post_feedback` (string)
    The message shown once the post-event feedback form is available, as HTML.

  - `post_feedback_publish_at` (string)
    When the post-event feedback form becomes available, as `YYYY-MM-DD HH:MM:SS`.

  - `training_ids` (array)
    The training people must have completed before they can apply, as a list of training ids.

  - `banner_image` (string)
    The event's banner image. Send the URL of an image already uploaded through Rosterfy, or the image itself as `multipart/form-data`. A URL on any other host is rejected.

  - `grid_image` (string)
    The image shown for the event in listings. Same accepted values as `banner_image`.

  - `mobile_banner_image` (string)
    The banner image used on smaller screens. Same accepted values as `banner_image`.

  - `minimum_dob` (string)
    The latest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `minimum_age`.

  - `minimum_age` (string)
    The youngest age allowed, as `years:months`, for example `16:0`. Cannot be combined with `minimum_dob`.

  - `maximum_dob` (string)
    The earliest date of birth allowed, as `YYYY-MM-DD`. Cannot be combined with `maximum_age`.

  - `maximum_age` (string)
    The oldest age allowed, as `years:months`. Cannot be combined with `maximum_dob`.

  - `public` (boolean)
    Whether the event is visible to people who are not signed in, on accounts that allow public browsing.

  - `public_shift` (boolean)
    Whether this event's shifts are visible to people who are not signed in.

  - `public_shift_default` (boolean)
    Whether a newly created shift on this event is public by default.

  - `token` (string)
    The event's public reference, the last part of its `rrn`. Generated when the event is created; there is rarely a reason to set your own.

  - `expression_of_interest` (boolean)
    Whether people may register interest in the event without applying for a specific shift.

  - `expression_of_interest_form` (integer)
    The form filled in when registering interest.

  - `shift_enable_waitlist_default` (boolean)
    Whether a full shift on this event takes a waitlist.

  - `max_waitlist` (integer)
    How many people a shift's waitlist holds.

  - `allow_user_activities` (boolean)
    Whether people may log their own activity against this event.

  - `user_activity_form_id` (integer)
    The form used to log that activity.

  - `approval_status` (string)
    Where the event sits in the account's approval process, when the account requires events to be approved.

  - `approval_reason` (string)
    Free text explaining the approval decision.

  - `is_ongoing` (boolean)
    Whether the event runs indefinitely rather than between two dates. Setting it clears the start and end.

  - `sort_order` (integer)
    Where the event sits when events are ordered manually. Lower comes first.

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

  - `object.event_template_id` (string | null)

  - `object.path` (string)

  - `object.account_id` (integer)

  - `object.event_type_id` (integer)

  - `object.journey_id` (string | null)

  - `object.timezone` (string)

  - `object.start_timestamp` (string)

  - `object.end_timestamp` (string)

  - `object.is_ongoing` (integer)

  - `object.apps_open_timestamp` (string)

  - `object.apps_close_timestamp` (string | null)

  - `object.headcount_location_venue_id` (string | null)

  - `object.headcount_functional_area_job_title_id` (string | null)

  - `object.shift_status_default` (integer)

  - `object.max_shift_apps_per_user` (integer)

  - `object.min_shift_apps_per_user` (integer)

  - `object.min_shift_apps_per_shift_type` (string | null)

  - `object.max_shift_apps_per_shift_type` (string | null)

  - `object.gap_between_shifts` (integer)

  - `object.shift_confirmed_status_default` (integer)

  - `object.shift_rejected_status_default` (integer)

  - `object.shift_can_withdraw_default` (integer)

  - `object.shift_can_confirm_default` (integer)

  - `object.shift_can_confirm_limit` (integer)

  - `object.shift_can_withdraw_limit` (integer)

  - `object.shift_checked_in_status_default` (integer)

  - `object.shift_checked_out_status_default` (integer)

  - `object.certificate_id` (string | null)

  - `object.shift_application_form_id_default` (string | null)

  - `object.shift_withdraw_form_id_default` (string | null)

  - `object.shift_checkin_form_id_default` (string | null)

  - `object.shift_attended_form_id_default` (string | null)

  - `object.shift_checkout_form_id_default` (string | null)

  - `object.shift_leader_feedback_form_id_default` (string | null)

  - `object.shift_feedback_form_id_default` (string | null)

  - `object.shift_precheckin_form_id_default` (string | null)

  - `object.shift_default_journey_complete_status` (string | null)

  - `object.shift_default_journey_id` (string | null)

  - `object.allow_user_activities` (integer)

  - `object.user_activity_form_id` (string | null)

  - `object.training_ids` (string | null)

  - `object.banner_image` (string | null)

  - `object.grid_image` (string | null)

  - `object.minimum_dob` (string | null)

  - `object.minimum_age` (string | null)

  - `object.maximum_dob` (string | null)

  - `object.maximum_age` (string | null)

  - `object.visibility_show_groups` (array)

  - `object.visibility_hide_groups` (array)

  - `object.visibility_show_roleoffer` (array)

  - `object.role_offer_address` (integer)

  - `object.checkin_visible_attributes` (array)

  - `object.shift_filter_attributes` (string | null)

  - `object.leader_shift_filter_attributes` (string | null)

  - `object.self_checkin` (integer)

  - `object.self_checkin_open` (integer)

  - `object.self_checkin_close` (integer)

  - `object.self_checkout_close` (integer)

  - `object.checkin_close_default` (integer)

  - `object.shift_precheckin_open_default` (integer)

  - `object.shift_enable_waitlist_default` (integer)

  - `object.geofence_checkin_limit_default` (string | null)

  - `object.max_waitlist` (integer)

  - `object.group_booking_ttl_default` (string | null)

  - `object.max_group_demand_default` (string | null)

  - `object.max_group_size` (string | null)

  - `object.reserved_expiry` (string | null)

  - `object.post_feedback_form` (string | null)

  - `object.post_feedback_publish_at` (string | null)

  - `object.expression_of_interest` (integer)

  - `object.journey_complete_status` (string | null)

  - `object.journey_apply_status` (string | null)

  - `object.expression_of_interest_form` (string | null)

  - `object.cancel_expression_of_interest_form_id` (string | null)

  - `object.eoi_demand` (integer)

  - `object.sort_order` (integer)

  - `object.is_virtual` (integer)

  - `object.status` (string)

  - `object.approval_status` (string)

  - `object.approval_reason` (string | null)

  - `object.promoted` (integer)

  - `object.public` (integer)

  - `object.is_cancelled` (integer)

  - `object.is_archived` (integer)

  - `object.public_shift` (integer)

  - `object.public_shift_default` (integer)

  - `object.token` (string)

  - `object.certificates_awarded` (integer)

  - `object.created_by` (string | null)

  - `object.updated_by` (string | null)

  - `object.deleted_at` (string | null)

  - `object.is_erased` (integer)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `object.deleted_by` (string | null)

  - `object.description` (string)

  - `object.name` (string)

  - `object.post_feedback` (string)

  - `object.tags` (string | null)

  - `object.address` (object)

  - `object.address.iso` (string)

  - `object.address.region_code` (string)

  - `object.address.coordinates` (object)

  - `object.address.coordinates.latitude` (string)

  - `object.address.coordinates.longitude` (string)

  - `object.address.street_address_1` (string)

  - `object.address.street_address_2` (string | null)

  - `object.address.street_address_3` (string | null)

  - `object.address.city` (string)

  - `object.address.postcode` (string)

  - `object.address.region` (string)

  - `object.address.country` (string)

  - `object.address.latitude` (string)

  - `object.address.longitude` (string)

  - `nice` (object)

  - `nice.rrn` (string)

  - `nice.address` (string)

  - `nice.address_oneline` (string)

  - `nice.address.country` (string)

  - `nice.address.country:raw` (string)

  - `nice.address.city` (string)

  - `nice.address.region` (string)

  - `nice.address.region:raw` (string)

  - `nice.address.postcode` (string)

  - `nice.address.street_address_1` (string)

  - `nice.address.street_address_2` (string | null)

  - `nice.address.street_address_3` (string | null)

  - `nice.address.latitude` (string)

  - `nice.address.longitude` (string)

  - `nice.allow_user_activities` (string)

  - `nice.approval_status` (string)

  - `nice.approval_status:value` (string)

  - `nice.approval_status:array` (string)

  - `nice.apps_open_timestamp` (string)

  - `nice.apps_open_timestamp__date` (string)

  - `nice.apps_open_timestamp__time` (string)

  - `nice.apps_open_timestamp__offset` (string)

  - `nice.apps_open_timestamp__offset_minutes` (integer)

  - `nice.apps_open_timestamp__dayofweek` (string)

  - `nice.cancel_expression_of_interest_form_id` (string | null)

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

  - `nice.cancel_expression_of_interest_form_id:array` (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.end_timestamp` (string)

  - `nice.end_timestamp__date` (string)

  - `nice.end_timestamp__time` (string)

  - `nice.end_timestamp__offset` (string)

  - `nice.end_timestamp__offset_minutes` (integer)

  - `nice.end_timestamp__dayofweek` (string)

  - `nice.event_template_id` (string | null)

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

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

  - `nice.event_type_id` (string)

  - `nice.event_type_id:value` (integer)

  - `nice.event_type_id:array` (string)

  - `nice.expression_of_interest` (string)

  - `nice.headcount_location_venue_id` (string | null)

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

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

  - `nice.is_ongoing` (string)

  - `nice.is_virtual` (string)

  - `nice.name` (string)

  - `nice.promoted` (string)

  - `nice.role_offer_address` (string)

  - `nice.self_checkin` (string)

  - `nice.shift_application_form_id_default` (string | null)

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

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

  - `nice.shift_attended_form_id_default` (string | null)

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

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

  - `nice.shift_checkin_form_id_default` (string | null)

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

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

  - `nice.shift_checkout_form_id_default` (string | null)

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

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

  - `nice.shift_feedback_form_id_default` (string | null)

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

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

  - `nice.shift_precheckin_form_id_default` (string | null)

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

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

  - `nice.shift_withdraw_form_id_default` (string | null)

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

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

  - `nice.start_timestamp` (string)

  - `nice.start_timestamp__date` (string)

  - `nice.start_timestamp__time` (string)

  - `nice.start_timestamp__offset` (string)

  - `nice.start_timestamp__offset_minutes` (integer)

  - `nice.start_timestamp__dayofweek` (string)

  - `nice.status` (string)

  - `nice.status:value` (string)

  - `nice.status:array` (string)

  - `nice.tags` (string | null)

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

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

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

  - `nice.visibility_show_groups` (string)

  - `nice.visibility_show_roleoffer` (string)

  - `nice.full_name` (string)

  - `nice.event_type_name` (string)

  - `nice.grid_list_image` (string | null)

  - `nice.is_eoi_demand_met` (boolean)

  - `nice.has_payrun` (boolean)

  - `nice.min_shifts` (integer)

  - `nice.post_event_feedback_form_completed_at` (string | null)

  - `nice.expression_of_interest_form_completed_at` (string | null)

  - `nice.expression_of_interest_form_cancelled_at` (string | null)

  - `nice.account_name` (string)

  - `relations` (array)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)

  - `permissions.apply` (boolean)

  - `permissions.cancel` (boolean)

  - `permissions.can_publish` (boolean)

  - `attributes` (object)