# Create a venue

Adds an addressable place under the location in the path. Roles are advertised
against venues rather than against the location itself, so a location needs at least
one before it can be recruited for.
Send `address` unless the venue is virtual. An address is not mandatory - a venue can
be created without one and given it later - but a venue with no address and
`is_virtual` unset is excluded from proximity searches until one is added.
**`description` is not read on create.** It is accepted by the update endpoint only;
a create that sends it returns `201` with the description unset. Add it in a
follow-up update.
**The created venue comes back with only the fields that were set on it**, not the
full record that reading it returns. Read the venue back if you need its complete
state.

Endpoint: POST /api/v2/headcount/location/{location_id}/venue
Version: 2.0.0
Security: default

## Path parameters:

  - `location_id` (integer, required)
    The ID of the location.

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `name` (string, required)
    The name administrators see. Required.

  - `frontend_name` (string, required)
    The name volunteers see in the portal. Required, and shown in place of `name` to anyone without administrator access, so it is worth setting even when the two match.

  - `code` (string, required)
    A short reference for the venue. Letters, numbers, commas, dashes and underscores only - spaces and other punctuation are rejected. Accounts configured to require unique venue codes reject a code already in use; otherwise codes may repeat.

  - `training_ids` (array)
    The IDs of the training modules assigned to anyone who accepts a role at this venue. **Replaces the whole list** rather than adding to it, so send every module you want kept. Omitting the field leaves the stored list untouched.

  - `is_virtual` (boolean)
    Whether the venue has no physical address. A virtual venue is excluded from proximity searches and sorts after venues that have coordinates. Setting this on an existing venue **detaches the address**, and switching it back off does not restore it - send the address again.

  - `address` (object)
    Where the venue is, as an address object with `street_address_1`, `street_address_2`, `street_address_3`, `city`, `region`, `postcode` and a two-letter `country`. Optional even for a venue that is not virtual. On create the address is stored as sent; on update it replaces the address already held. Ignored when `is_virtual` is set in the same request.

## Response 201 fields (application/json):

  - `object` (object)

  - `object.name` (string)

  - `object.frontend_name` (string)

  - `object.code` (string)

  - `object.training_ids` (array)

  - `object.is_virtual` (integer)

  - `object.headcount_location_id` (integer)

  - `object.uuid` (string)

  - `object.updated_at` (string)

  - `object.created_at` (string)

  - `object.id` (integer)

  - `object.address` (object)

  - `object.address.iso` (string)

  - `object.address.region_code` (string)

  - `object.address.coordinates` (object)

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

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

  - `object.address.street_address_1` (string)

  - `object.address.city` (string)

  - `object.address.region` (string)

  - `object.address.postcode` (string)

  - `object.address.country` (string)

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

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

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

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

  - `nice.location_name` (string)

  - `nice.headcount_location_type_name` (string)

  - `nice.headcount_location_type_id` (integer)

  - `relations` (object)

  - `relations.location` (object)

  - `relations.location.object` (object)

  - `relations.location.object.id` (integer)

  - `relations.location.object.account_id` (integer)

  - `relations.location.object.headcount_location_type_id` (integer)

  - `relations.location.object.name` (string)

  - `relations.location.object.frontend_name` (string)

  - `relations.location.object.code` (string)

  - `relations.location.object.training_ids` (array)

  - `relations.location.object.is_system` (integer)

  - `relations.location.object.deleted_at` (string | null)

  - `relations.location.object.created_at` (string)

  - `relations.location.object.updated_at` (string)

  - `relations.location.object.uuid` (string)

  - `relations.location.nice` (object)

  - `relations.location.nice.rrn` (string)

  - `relations.location.nice.headcount_location_type_name` (string)

  - `relations.location.permissions` (object)

  - `relations.location.permissions.read` (boolean)

  - `relations.location.permissions.update` (boolean)

  - `relations.location.permissions.delete` (boolean)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)