# Conundra Resources API The Resources API provides the resources necessary to create a planning. Version: 1.27.2 ## Servers Resources API Production ``` https://api.conundra.eu/resource-management/v1 ``` ## Security ### clientCredentials This API uses OAuth2 with the Client Credentials flow for M2M communication. Client ID ans secret should be provided as a HTTP Basic Auth header. Type: oauth2 ## Download OpenAPI description [Conundra Resources API](https://developer.conundra.eu/_bundle/apis/resource-management/resources-api.yaml) ## Health check Miscellaneous endpoints for general API functionality ### Health check - [GET /ping](https://developer.conundra.eu/apis/resource-management/resources-api/health/ping.md): The ping-endpoint can be used for validating a connection with the application. It will authenticate the caller and respond pong if everything is set-up correctly. ## Employee Endpoints used for managing the general information regarding your `Employees`. These endpoints are meant for managing `Employees` whose role is relevant for the functionality in Resource Management, ie: typically only those `Employees` capable of operating `TransportResources`. ### Get cursor-based employees - [GET /employee](https://developer.conundra.eu/apis/resource-management/resources-api/employee/getpagedemployees.md): Retrieve employees in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal). ### Upsert Employee - [PUT /employee/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee/upsertemployee.md): Create or update an Employee. A unique ID (business_id) is required to identify the Employee. Calling this endpoint with an existing business_id will update the Employee. Modifying (or retrieving) an Employee will provide the caller with a version number for this Employee. This version can be passed to the _upsert_ endpoint as a _weak ETag_ in the If-Match header. This allows the caller to ensure that the Employee has not been modified since the last time it was retrieved. ### Get Employee - [GET /employee/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee/getemployee.md): Get an existing Employee, defined by their business_id. ### Delete Employee - [DELETE /employee/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee/deleteemployee.md): Delete an Employee, defined by their business_id. Removing an Employee will remove all related sub-resources. Note: Deployed ResourceCombinations (eg: used in a released route in an optimization) will not be removed. ## Shift Schedule `ShiftSchedules` can be used to describe the recurring pattern for an `Employee`'s availability. They do not trigger availabilities themselves, but can be used to generate availabilities according to this schedule, through the application's user interface. Providing `ShiftSchedules` enables planners to do long-term planning using the _Employee Overview_ in the UI, since this allows us to predict when an `Employee` _should_ be available. ### Create Shift Schedule - [POST /employee/{business_id}/shift-schedule](https://developer.conundra.eu/apis/resource-management/resources-api/shift-schedule/createshiftschedule.md): Endpoint to create a ShiftSchedule. 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). ### Get all Shift Schedules by Employee - [GET /employee/{business_id}/shift-schedule](https://developer.conundra.eu/apis/resource-management/resources-api/shift-schedule/getshiftschedulesbyemployeeid.md): Retrieve all ShiftSchedules for a given Employee, identified by their business id. ### Update Shift Schedule - [PUT /employee/{business_id}/shift-schedule/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/shift-schedule/updateshiftschedule.md): Update an existing ShiftSchedule for an Employee. The generated_id is determined by the application and was returned on creation. A list of existing ShiftSchedules can be retrieved by using the getShiftSchedulesByEmployeeId endpoint. ### Delete Shift Schedule - [DELETE /employee/{business_id}/shift-schedule/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/shift-schedule/deleteshiftschedule.md): Update an existing ShiftSchedule for an Employee. The generated_id is determined by the application and was returned on creation. A list of existing ShiftSchedules can be retrieved by using the getShiftSchedulesByEmployeeId endpoint. ## Availability `Availabilities` define a specific time range during which an `Employee` is available to execute tasks. These can either be derived from a `ShiftSchedule` (via the user interface) or created on an ad-hoc basis. When an `Availability` is created or updated, it triggers a consolidation process that generates a snapshot of the corresponding `Employee` at that moment, referred to as an `AvailableEmployee`. This snapshot accounts for relocations (managed through the user interface) and `Unavailabilities`, ensuring a single source of truth for the `Employee`'s status at that point in time. Any modifications to this `AvailableEmployee` snapshot activate an algorithm that evaluates potential `ResourceCombinations` involving the `Employee`'s `Availability`. During this evaluation, potential `TransportResources` are assessed. If the heuristic identifies that a specific `ResourceCombination` would enhance the overall solution's fitness, it is either created or updated. ### Get all Employee Availabilities - [GET /employee/{business_id}/availability](https://developer.conundra.eu/apis/resource-management/resources-api/availability/getemployeeavailabilities.md): Retrieves all Availabilities for a single Employee (identified by their business_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_start up 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). ### Create Employee Availability - [POST /employee/{business_id}/availability](https://developer.conundra.eu/apis/resource-management/resources-api/availability/addemployeeavailability.md): 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. ### Delete Employee Availabilities - [DELETE /employee/{business_id}/availability](https://developer.conundra.eu/apis/resource-management/resources-api/availability/deleteemployeeavailabilities.md): Delete all existing Employee Availabilities that overlap using an open or closed a time range. Overlap is determined for the widest possible range on an Availability, ie: earliest_start up until (calculated) latest_stop. Note: Any overlapping Availabilities will be removed, an Availability can be partially outside of the provided time range. ### Get Employee Availability - [GET /employee/{business_id}/availability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/availability/getemployeeavailability.md): Retrieve an existing Availability, identified by its generated_id, for an Employee, identified by their business_id. ### Update Employee Availability - [PUT /employee/{business_id}/availability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/availability/updateemployeeavailability.md): Update a specific Availability, identified by its generated_id, for an Employee, identified by their business_id. The updated Availability should not overlap with existing Availabilities. ### Delete Employee Availability by id - [DELETE /employee/{business_id}/availability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/availability/deleteemployeeavailability.md): Delete an existing Availability, identified by its generated_id, for an Employee, identified by their business_id. This will remove a ResourceCombination tied to this Availability if it was not deployed by releasing a route in an optimization. ## Unavailability [EXPERIMENTAL] `Unavailabilities` define a specific time range during which an `Employee` is unavailable to execute tasks. This can be due to sickness, holiday, or other temporary absences. During its duration, the employee can not be matched with a transport resource and used as part of the planning. ### [EXPERIMENTAL] Create Employee Unavailability - [POST /employee/{business_id}/unavailability](https://developer.conundra.eu/apis/resource-management/resources-api/employee-unavailability/createemployeeunavailability.md): Create an unavailability for an employee ### [EXPERIMENTAL] Get all Employee Unavailabilities by Employee business id - [GET /employee/{business_id}/unavailability](https://developer.conundra.eu/apis/resource-management/resources-api/employee-unavailability/getemployeeunavailabilities.md): Get all Employee Unavailabilities by Employee business id. When a from and until are provided, we match any Unavailabilities that overlap with this range. ### [EXPERIMENTAL] Upsert Employee Unavailability - [PUT /employee/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee-unavailability/upsertemployeeunavailability.md): Create or update an unavailability for an employee. ### [EXPERIMENTAL] Delete Employee Unavailability by id - [DELETE /employee/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee-unavailability/deleteemployeeunavailability.md) ### [EXPERIMENTAL] Get Employee Unavailability by id - [GET /employee/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/employee-unavailability/getemployeeunavailability.md) ## Transport Resource Endpoints used for managing the general information regarding your `Transport Resources`. These can be `Trucks`, `Trailers` and `Tractors`. ### Get cursor-based transport resources - [GET /transport-resource](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource/getpagedtransportresources.md): Retrieve transport resources in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal). ### Upsert Transport Resource - [PUT /transport-resource/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource/upserttransportresource.md): Upsert a single TransportResource. As a TransportResource is considered to be always available unless a TransportResourceUnavailability says otherwise, its presence will result in the application trying to create ResourceCombinations by matching AvailableEmployees with this TransportResource. ### Get Transport Resource by business id - [GET /transport-resource/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource/gettransportresource.md): Get an existing TransportResource ### Delete Transport Resource by business id - [DELETE /transport-resource/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource/deletetransportresource.md): Delete an existing TransportResource. Upon deleting, the application will also remove ResourceCombinations using this TransportResource and try to find replacements. All unavailabilities and relocations related to this TransportResource will be removed as well. ## Unavailability [EXPERIMENTAL] `Unavailabilities` define a specific time range during which a `TransportResource` is unavailable. This can be due to, for example, technical issues. During its duration, the `TransportResource` can not be matched with an available `Employee` and used as part of the planning. ### [EXPERIMENTAL] Create TransportResource Unavailability - [POST /transport-resource/{business_id}/unavailability](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource-unavailability/addtransportresourceunavailability.md): This endpoint allows you to create an Unavailability with a generated ID. This can be used for _ad hoc_ Unavailabilities or situations where the source system does not contain any unique IDs. See the PUT operation for more information on the functional impact of adding a new unavailability. ### [EXPERIMENTAL] Get all TransportResource Unavailabilities by TransportResource business id - [GET /transport-resource/{business_id}/unavailability](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource-unavailability/gettransportresourceunavailabilities.md): Get all TransportResource Unavailabilities by TransportResource business id. When a from and until are provided, we match any Unavailabilities that overlap with this range. ### [EXPERIMENTAL] Upsert TransportResource Unavailability - [PUT /transport-resource/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource-unavailability/upserttransportresourceunavailability.md): Create or update a TransportResourceUnavailability. When a TransportResource becomes unavailable, the ResourceCombinations whose guaranteed working time overlapped with the unavailability are deleted. For other overlaps the existing combinations are only re-evaluated. ### [EXPERIMENTAL] Delete TransportResource Unavailability by id - [DELETE /transport-resource/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource-unavailability/deletetransportresourceunavailability.md) ### [EXPERIMENTAL] Get TransportResource Unavailability by id - [GET /transport-resource/{business_id}/unavailability/{generated_id}](https://developer.conundra.eu/apis/resource-management/resources-api/transport-resource-unavailability/gettransportresourceunavailability.md) ## Home Base [EXPERIMENTAL] A `Home Base` is a reusable address that is used to specify the location of `Employees` or `Transport Resources`. Instead of specifying a full address for each of these, the user can create a single reusable `HomeBase` and assign it to all. Updates to an assigned `HomeBase` are propagated to all future resources using it. ### Get cursor-based home bases - [GET /home-base](https://developer.conundra.eu/apis/resource-management/resources-api/homebase/getpagedhomebases.md): Retrieve home bases in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal). ### [EXPERIMENTAL] Upsert Home Base - [PUT /home-base/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/homebase/upserthomebase.md): Upsert a single HomeBase. Once it is created Employees and Transport Resources can make use of it. ### [EXPERIMENTAL] Get Home Base - [GET /home-base/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/homebase/gethomebase.md): Get a single HomeBase. ### [EXPERIMENTAL] Delete Home Base - [DELETE /home-base/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/homebase/deletehomebase.md): Delete a single HomeBase. A HomeBase can only be deleted when there are no resources left referring to it. ## Forecast [EXPERIMENTAL] A forecast is the expected the number of shifts that will be required on the given day and location. They is used in the context of capacity planning: a difference in the forecast and the available shifts can indicate ue in the planning. The provided forecasts are only used to show to the end user and are not taken into account for any of the calculations made by the application. ### [EXPERIMENTAL] Upsert Forecast - [PUT /resource-overview/{date}/{location}/forecasts](https://developer.conundra.eu/apis/resource-management/resources-api/forecast/upsertforecast.md): Upsert a single Forecast ### [EXPERIMENTAL] Get Forecast - [GET /resource-overview/{date}/{location}/forecasts](https://developer.conundra.eu/apis/resource-management/resources-api/forecast/getforecast.md): Get a single Forecast. ### [EXPERIMENTAL] Delete Forecast - [DELETE /resource-overview/{date}/{location}/forecasts](https://developer.conundra.eu/apis/resource-management/resources-api/forecast/deleteforecast.md): Delete a single Forecast. ## Deployment [EXPERIMENTAL] Endpoints used for managing `Deployments`. A `Deployment` represents the actual assignment of an `Employee` to one or more `TransportResources` for a specific time period and location. External deployments can be created to represent work assignments that are managed outside of the Resource Management system. Releasing or unreleasing routes in PTV OptiFlow also manages `Deployments`. These `Deployments` are managed internally by Resource Management and cannot be modified by this API. ### [EXPERIMENTAL] Get cursor-based deployments - [GET /deployment](https://developer.conundra.eu/apis/resource-management/resources-api/deployment/getpageddeployments.md): Retrieve deployments in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal). Deployments without a planning_id are externally managed Deployments. Deployments with a planning_id are managed by releasing or unreleasing routes in PTV OptiFlow. ### [EXPERIMENTAL] Get Deployment - [GET /deployment/{id}](https://developer.conundra.eu/apis/resource-management/resources-api/deployment/getdeployment.md): Get an existing Deployment, defined by their id. Deployments without a planning_id are externally managed Deployments. Deployments with a planning_id are managed by releasing or unreleasing routes in PTV OptiFlow. ### [EXPERIMENTAL] Upsert External Deployment - [PUT /deployment/{id}](https://developer.conundra.eu/apis/resource-management/resources-api/deployment/upsertexternaldeployment.md): Create or update an external Deployment. A unique ID (id) is required to identify the Deployment. Calling this endpoint with an existing id will update the Deployment. External Deployments represent work assignments that are managed outside of the Resource Management system. We don't allow overlap between Deployments for the same Employee or Transport Resource. ### [EXPERIMENTAL] Delete External Deployment - [DELETE /deployment/{id}](https://developer.conundra.eu/apis/resource-management/resources-api/deployment/deleteexternaldeployment.md): Delete an external Deployment, defined by their id. It is not possible to delete Deployments that are managed by the PTV OptiFlow platform. In order to remove these Deployments, you can use the planning_id to unrelease the corresponding route in the PTV OptiFlow planning. ## Actual `Actuals` capture the worked hours for an `Employee` during a completed work shift. This data is used to provide insights into actual worked hours compared to contractual hours, and also helps steer the optimization algorithm towards creating a balanced work week that fulfills contractual hours without significant undershooting or overshooting. By their nature, `Actuals` should always represent completed work shifts and therefore should always be in the past, adding `Actuals` that end in the future could lead to undesired behaviour. ### Get cursor-based actuals for an employee - [GET /means/{employee_id}/actual](https://developer.conundra.eu/apis/resource-management/resources-api/actual/getpagedemployeeactuals.md): Retrieve actuals for an employee in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal). ### [EXPERIMENTAL] Upsert Actual - [PUT /means/{employee_id}/actual/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/actual/upsertactual.md): Upsert a single Actual for an Employee. ### [EXPERIMENTAL] Get Actual - [GET /means/{employee_id}/actual/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/actual/getactual.md): Get a single Actual for an Employee. ### [EXPERIMENTAL] Delete Actual - [DELETE /means/{employee_id}/actual/{business_id}](https://developer.conundra.eu/apis/resource-management/resources-api/actual/deleteactual.md): Delete a single Actual for an Employee.