# Create Employee Availability

Add an Availability for an Employee. An identifier will be generated by the application. This identifier can be retrieved from the Location header, 
or response body (if the Prefer header is set to return=representation).

New Availabilities should not overlap with existing Availabilities.

Endpoint: POST /employee/{business_id}/availability
Version: 1.27.2
Security: clientCredentials

## Path parameters:

  - `business_id` (string, required)
    The unique identifier of the Employee for whom to create an Availability.

## Header parameters:

  - `Prefer` (array)
    The RFC7240 Prefer header indicates that a particular server behavior
is preferred by the client but is not required for successful completion
of the request (see RFC 7240).

The following behavior (see _Examples_) is supported by this API:
* return= is used to suggest the server to
  return using 204 without resource (minimal) or using 200 or 201 with
  resource (representation) in the response body on success.

## Request fields (application/json):

  - `start_location` (object)
    An ad-hoc location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the 
Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based 
match), unless that employee is on a Journey. In that case they will continue to use the same TransportResource until the Journey is done.

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

  - `start_location.address` (object)
    An ad-hoc location from which this Employee will start this specific work Availability. This overrides the  ad-hoc start_location or home base on the 
Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based 
match).

Either address information or geo point must be provided. Resolved address information will be read only and be filled out after resolving. 

An ad-hoc start_location is mutually exclusive with providing a home_base or setting at_last_end, but neither are mandatory for an Availability.

  - `start_location.address.name` (string, required)
    A name by which to identify this location. If used as a start_location, this is used for matching colocated entities.
    Example: "Conundra"

  - `start_location.address.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
    Example: "Voordries 41b"

  - `start_location.address.city` (string)
    The name of the locality of this location.

Required when no geo_point is provided.
    Example: "Oosterzele"

  - `start_location.address.zip_code` (string)
    The ZIP code of the locality of this location.

Required when no geo_point is provided.
    Example: "9860"

  - `start_location.address.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.

Required when no geo_point is provided.

  - `start_location.address.geo_point` (object)

  - `start_location.address.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `start_location.address.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `start_location.home_base` (object)
    The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this Availability, unless otherwise specified on more specific entities. When located at a HomeBase, the Employee will only be assigned to TransportResources with a matching home_base. 
This is conceptually the same as using an ad-hoc address but with centralized address management which automatically propagates changes on the 
root entity.

A home_base is mutually exclusive with providing an address or setting at_last_end, but neither are mandatory for an Availability.

  - `start_location.home_base.business_id` (string, required)
    The unique identifier of a HomeBase.
    Example: "depot-1"

  - `start_location.at_last_end` (boolean)
    When this is set, the planning will use the end location of the preceding deployed ResourceCombination as the starting point for this one.

This is mutually exclusive with providing an address or a home_base, but neither are mandatory for an Availability.

  - `start_location.name` (string)
    A name by which to identify this location. If used as a start_location, this is used for matching coloecated entities.
Deprecated in favor of the address field.
This is required only when using the deprecated fields.
    Example: "Conundra"

  - `start_location.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
Deprecated in favor of the address field.
    Example: "Voordries 41b"

  - `start_location.city` (string)
    The name of the locality of this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.
    Example: "Oosterzele"

  - `start_location.zip_code` (string)
    The ZIP code of the locality of this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.
    Example: "9860"

  - `start_location.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.

  - `start_location.geo_point` (object)
    Deprecated in favor of the address field.

  - `end_location` (object)
    [EXPERIMENTAL] Property to define an endLocation. When left blank, the Employee will make a round-trip and the endLocation will match the startLocation.

Only one option is allowed, either address, home_base or at_last_activity can be set.

  - `end_location.address` (object)
    An ad-hoc address where this Employee will end during this specific Availability. 

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

  - `end_location.home_base` (object)
    The business_id of a know HomeBase where this Employee will end during this specific Availability.

  - `end_location.at_last_activity` (boolean)
    The optimization will determine the best (eg: most cost-effective) location. This location will always be an Order's location. This option can only 
be honored for plannings that do a PickupDelivery optimization. When set for other types of plannings, the optimization will result in a round trip.

  - `earliest_start` (string, required)
    The earliest instant that the Employee can start this work shift.
    Example: "2021-01-01T04:15:30Z"

  - `latest_start` (string)
    The latest instant that the Employee can start this work shift. If not provided, the optimization will potentially introduce wait time starting from
the earliest_start if this Employee is used to execute tasks.
    Example: "2021-01-01T06:00:00Z"

  - `latest_stop` (string)
    The latest time at which the availability should end. This can be useful for defining schedules with a lenient start window, but where the Employee 
has a hard stop at a certain time. It should be between (earliest_start + min_duration) and (latest_start + max_duration).

If no latest_stop is provided, it will be extrapolated from the latest_start and max_duration properties.
    Example: "2021-01-01T16:00:00Z"

  - `min_duration` (string)
    The minimal duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string. If no min_duration is provided, the application
will treat the max_duration as the min_duration when it needs to determine the timeframe in which this shift ends.
    Example: "PT8H"

  - `max_duration` (string, required)
    The maximum duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string.
    Example: "PT12H"

  - `mandatory` (boolean)
    Indicates whether the resulting combination is required to be used when planned
    Example: true

  - `home_base_id` (string)
    The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this specific work shift. This 
overrides the  ad-hoc start_location or home base on the Employee.  When located at a HomeBase, the Employee will only be assigned to TransportResources 
with a matching home_base. This is conceptually the same as using an ad-hoc start_location, but with centralized address management which automatically 
propagates changes on the root HomeBase entity.

A home_base is mutually exclusive with providing an ad-hoc start_location, but neither is mandatory for an Availability.

Deprecated in favor of the start_location property.
    Example: "a-home-base-id"

## Response 201 fields (application/json):

  - `id` (string)
    The unique Availability ID.
    Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"

  - `employee_id` (string)
    The unique Employee ID.

  - `start_location` (object)
    An ad-hoc location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the 
Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based 
match), unless that employee is on a Journey. In that case they will continue to use the same TransportResource until the Journey is done.

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

  - `start_location.address` (object)
    An ad-hoc location from which this Employee will start this specific work Availability. This overrides the  ad-hoc start_location or home base on the 
Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based 
match).

Either address information or geo point must be provided. Resolved address information will be read only and be filled out after resolving. 

An ad-hoc start_location is mutually exclusive with providing a home_base or setting at_last_end, but neither are mandatory for an Availability.

  - `start_location.address.name` (string, required)
    A name by which to identify this location. If used as a start_location, this is used for matching colocated entities.
    Example: "Conundra"

  - `start_location.address.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
    Example: "Voordries 41b"

  - `start_location.address.city` (string)
    The name of the locality of this location.

Required when no geo_point is provided.
    Example: "Oosterzele"

  - `start_location.address.zip_code` (string)
    The ZIP code of the locality of this location.

Required when no geo_point is provided.
    Example: "9860"

  - `start_location.address.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.

Required when no geo_point is provided.

  - `start_location.address.geo_point` (object)

  - `start_location.address.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `start_location.address.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `start_location.address.geo_point.resolved` (object)
    Indicates whether the address is resolved.

  - `start_location.address.geo_point.resolved.geocoded` (boolean)
    Example: true

  - `start_location.address.geo_point.resolved.address` (string)
    Example: "Voordries 31 bus B, 9860 Oosterzele"

  - `start_location.address.geo_point.resolved.precision` (integer)
    Example: 9

  - `start_location.home_base` (object)
    The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this Availability, unless otherwise specified on more specific entities. When located at a HomeBase, the Employee will only be assigned to TransportResources with a matching home_base. 
This is conceptually the same as using an ad-hoc address but with centralized address management which automatically propagates changes on the 
root entity.

A home_base is mutually exclusive with providing an address or setting at_last_end, but neither are mandatory for an Availability.

  - `start_location.home_base.business_id` (string, required)
    The unique identifier of a HomeBase.
    Example: "depot-1"

  - `start_location.at_last_end` (boolean)
    When this is set, the planning will use the end location of the preceding deployed ResourceCombination as the starting point for this one.

This is mutually exclusive with providing an address or a home_base, but neither are mandatory for an Availability.

  - `start_location.name` (string)
    A name by which to identify this location. If used as a start_location, this is used for matching coloecated entities.
Deprecated in favor of the address field.
This is required only when using the deprecated fields.
    Example: "Conundra"

  - `start_location.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
Deprecated in favor of the address field.
    Example: "Voordries 41b"

  - `start_location.city` (string)
    The name of the locality of this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.
    Example: "Oosterzele"

  - `start_location.zip_code` (string)
    The ZIP code of the locality of this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.
    Example: "9860"

  - `start_location.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.
Required when no geo_point is provided.
Deprecated in favor of the address field.

  - `start_location.geo_point` (object)
    Deprecated in favor of the address field.

  - `end_location` (object)
    [EXPERIMENTAL] Property to define an endLocation. When left blank, the Employee will make a round-trip and the endLocation will match the startLocation.

Only one option is allowed, either address, home_base or at_last_activity can be set.

  - `end_location.address` (object)
    An ad-hoc address where this Employee will end during this specific Availability. 

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

  - `end_location.home_base` (object)
    The business_id of a know HomeBase where this Employee will end during this specific Availability.

  - `end_location.at_last_activity` (boolean)
    The optimization will determine the best (eg: most cost-effective) location. This location will always be an Order's location. This option can only 
be honored for plannings that do a PickupDelivery optimization. When set for other types of plannings, the optimization will result in a round trip.

  - `earliest_start` (string, required)
    The earliest instant that the Employee can start this work shift.
    Example: "2021-01-01T04:15:30Z"

  - `latest_start` (string)
    The latest instant that the Employee can start this work shift. If not provided, the optimization will potentially introduce wait time starting from
the earliest_start if this Employee is used to execute tasks.
    Example: "2021-01-01T06:00:00Z"

  - `latest_stop` (string)
    The latest time at which the availability should end. This can be useful for defining schedules with a lenient start window, but where the Employee 
has a hard stop at a certain time. It should be between (earliest_start + min_duration) and (latest_start + max_duration).

If no latest_stop is provided, it will be extrapolated from the latest_start and max_duration properties.
    Example: "2021-01-01T16:00:00Z"

  - `min_duration` (string)
    The minimal duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string. If no min_duration is provided, the application
will treat the max_duration as the min_duration when it needs to determine the timeframe in which this shift ends.
    Example: "PT8H"

  - `max_duration` (string, required)
    The maximum duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string.
    Example: "PT12H"

  - `mandatory` (boolean)
    Indicates whether the resulting combination is required to be used when planned
    Example: true

  - `home_base_id` (string)
    The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this specific work shift. This 
overrides the  ad-hoc start_location or home base on the Employee.  When located at a HomeBase, the Employee will only be assigned to TransportResources 
with a matching home_base. This is conceptually the same as using an ad-hoc start_location, but with centralized address management which automatically 
propagates changes on the root HomeBase entity.

A home_base is mutually exclusive with providing an ad-hoc start_location, but neither is mandatory for an Availability.

Deprecated in favor of the start_location property.
    Example: "a-home-base-id"

## Response 400 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: "Validation exception"

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: "The field contains invalid business formatting."

  - `violations` (array)

  - `violations.field` (string)
    Example: "path.to.field"

  - `violations.message` (string)
    Example: "Field is required"

## Response 404 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: "Validation exception"

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: "The field contains invalid business formatting."

## Response 409 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: "Validation exception"

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: "The field contains invalid business formatting."


## Response 204 fields

## Response 401 fields