Get Employee Availability

Request

Retrieve an existing Availability, identified by its generated_id, for an Employee, identified by their id.

Security

clientCredentials

Path

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

The unique identifier of the Employee for whom to retrieve an Availability.

generated_idstring, (uuid)required

The unique identifier of the Availability to retrieve.

Payload

// No request payload

Responses

Employee Availability is retrieved

Headers

ETagstring

A weak Etag (ex W/"<etag_value>") which contains the current version of the entity

Example:"W/\"25\""

Bodyapplication/json

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

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": {
    "address": { … },
    "home_base": { … },
    "at_last_end": false,
    "name": "PTV Logistics",
    "address_line": "Voordries 41b",
    "city": "Oosterzele",
    "zip_code": "9860",
    "country_code": "BE",
    "geo_point": { … }
  },
  "home_base_id": "a-home-base-id",
  "end_location": {
    "address": { … },
    "home_base": { … },
    "at_last_activity": false
  },
  "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
}