Get all Employee Availabilities

Request

Retrieves all Availabilities for a single Employee (identified by their id) within an optional time range.

This endpoint will return any overlapping Availability, so it is possible for the returned Availability to have a time range that spills outside of the provided time range. Overlap is determined for the widest possible range on an Availability, ie: earliest_startup until (calculated)latest_stop`.

When providing a time range, it can be open (either from or until is provided) or closed (both from and until are provided).

Security

clientCredentials

Path

employee_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

The unique identifier of the Employee for whom to retrieve Availabilities.

Query

fromstring, (date-time)

The start of the time range to retrieve Availabilities for. If not provided, the time range will be open-ended, starting from the earliest Availability for this Employee.

Example:from=2021-01-01T10:15:30Z

untilstring, (date-time)

The end of the time range to retrieve Availabilities for. If not provided, the time range will be open-ended, ending at the latest Availability for this Employee.

If both from and until are provided, until must not be lower than from.

Example:until=2021-01-05T10:15:30Z

Payload

// No request payload

Responses

Employee Availabilities that overlap with the provided time range. This list can be empty. Each item contains the Availability's version for optimistic locking purposes.

Bodyapplication/json

Array [

idstringread-only

The unique Availability ID.

Example:"f22896d0-ed42-4a14-a935-7a29072bc5ac"

employee_idstring(EmployeeId)^[a-zA-Z0-9.~\-_]+$read-only

The unique Employee ID.

Example:"employee-42"

start_locationobject(AvailabilityStartLocation)

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.

end_locationobject(EndLocation)

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

earliest_startstring, (date-time)required

The earliest instant that the Employee can start this work shift.

Example:"2021-01-01T04:15:30Z"

latest_startstring, (date-time)

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_stopstring, (date-time)

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_durationstring

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_durationstringrequired

The maximum duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string.

Example:"PT12H"

mandatoryboolean

Indicates whether the resulting combination is required to be used when planned

Default:false

Example:true

versioninteger(Version)

Version of the entity, can be used for optimistic locking.

Example:42

home_base_idstringdeprecated

The 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

[
  {
    "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
    "employee_id": "employee-42",
    "start_location": { … },
    "home_base_id": "a-home-base-id",
    "end_location": { … },
    "earliest_start": "2021-01-01T04:15:30Z",
    "latest_start": "2021-01-01T06:00:00Z",
    "latest_stop": "2021-01-01T16:00:00Z",
    "min_duration": "PT8H",
    "max_duration": "PT12H",
    "mandatory": true,
    "version": 42
  }
]