Create or update a request

This endpoint allows to update or create a request for an employee.

PUT /api/v1/businesses/{businessId}/requests

Below are the fields that make up the request body, some of which are mandatory for the request to be successful.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis

JSON Analysis
`{ "employeeId": "string", "status": "string", "type": "string", "from": "string", "to": "string", "fromHour": "string", "toHour": "string", "comments": "string", "recover": "string" }` Details employeeId: external identifier of the employee. status: status of the request. The accepted values are `REQUESTED`, `GRANTED` and `DENIED`. type*: type of availability that applies to the request. The accepted values are: `NON_WORKED` (day off), `MAYBE` (availability without obligation to be in the indicated interval), `MANDATORY` (availability to work mandatory in that interval) and `SHIFT` (requested shift). The `MAYBE`, `MANDATORY` and `SHIFT` types require `fromHour` and `toHour` to be provided; `NON_WORKED` must not include them. from**: start date of the request in `yyyy-MM-dd` format. to: end date of the request in `yyyy-MM-dd` format. fromHour: start time of the request in `HH:mm` format. Refers to local time, that is, the time zone of the service. toHour: end time of the request in `HH:mm` format. Refers to local time, that is, the time zone of the service. comments: reason or explanation for making the request. recover: type of recovery indicating how the employee’s request could be compensated. The options are `FREE` (free day) or `NONE`.

{
  "employeeId": "string",
  "status": "string",
  "type": "string",
  "from": "string",
  "to": "string",
  "fromHour": "string",
  "toHour": "string",
  "comments": "string",
  "recover": "string"
}

Details

employeeId*: external identifier of the employee.
status*: status of the request. The accepted values are REQUESTED, GRANTED and DENIED.
type*: type of availability that applies to the request. The accepted values are: NON_WORKED (day off), MAYBE (availability without obligation to be in the indicated interval), MANDATORY (availability to work mandatory in that interval) and SHIFT (requested shift). The MAYBE, MANDATORY and SHIFT types require fromHour and toHour to be provided; NON_WORKED must not include them.
from*: start date of the request in yyyy-MM-dd format.
to*: end date of the request in yyyy-MM-dd format.
fromHour: start time of the request in HH:mm format. Refers to local time, that is, the time zone of the service.
toHour: end time of the request in HH:mm format. Refers to local time, that is, the time zone of the service.
comments: reason or explanation for making the request.
recover: type of recovery indicating how the employee’s request could be compensated. The options are FREE (free day) or NONE.

Request example

After analyzing the different fields, here is an example of the request body:

{
  "employeeId": "00001",
  "status": "REQUESTED",
  "type": "MAYBE",
  "from": "2024-07-25",
  "to": "2024-07-25",
  "fromHour": "10:00",
  "toHour": "12:00",
  "comments": "I could work at this time, depending on my other shifts.",
  "recover": "NONE"
}

If all data is correct, a request will be generated with the following characteristics:

Status: requested.
Day: July 25, 2024.
Availability from 10:00 to 12:00.
Worked? Maybe.

Additionally, the reason for making the request will be added.

Considerations

If a request already exists for the same employee, day and concept, the request replaces it instead of returning a duplicate error — hence the endpoint serves both to create and to update.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

Code	Message	Description
`406 Not Acceptable`	Employee id is mandatory	The `employeeId` field is missing.
Status is mandatory	The `status` field is missing.
Type is mandatory	The `type` field is missing.
From date cannot be null	The `from` field is missing.
To date cannot be null	The `to` field is missing.
Request time range is invalid	The `to` date is earlier than the `from` date.
Status must be one of REQUESTED, GRANTED or DENIED	The `status` value is not one of the accepted ones.
Type must be one of MAYBE, MANDATORY, SHIFT or NON_WORKED	The `type` value is not one of the accepted ones.
Non worked request cannot have fromHour or toHour	The `NON_WORKED` type does not accept the `fromHour` or `toHour` fields with a value (`null` is accepted), as it is a request for a full day off.
Shift request must have from and to hour	The `SHIFT` type does not include the `fromHour` or `toHour` fields, which are mandatory for this type of request.
`400 Bad Request`	-	The request body is not valid JSON or one of its fields does not have the expected format.
error.request_out_of_service_association	The request period does not match any of the employee’s current service associations.
error.request_out_of_period	The request falls outside the period editable by the current user.
error.request_duplicated_concepts	A request with the same concept already exists in that period.
error.request_overlapped_concepts	The request overlaps with another one of an incompatible concept.
error.person_request_not_allowed_for_day_type	The configured day type does not accept this type of request.
error.person_request_weekly_limit_exceeded	The weekly limit of requests of this type has been exceeded.

406 Not Acceptable

Employee id is mandatory

The employeeId field is missing.

Status is mandatory

The status field is missing.

Type is mandatory

The type field is missing.

From date cannot be null

The from field is missing.

To date cannot be null

The to field is missing.

Request time range is invalid

The to date is earlier than the from date.

Status must be one of REQUESTED, GRANTED or DENIED

The status value is not one of the accepted ones.

Type must be one of MAYBE, MANDATORY, SHIFT or NON_WORKED

The type value is not one of the accepted ones.

Non worked request cannot have fromHour or toHour

The NON_WORKED type does not accept the fromHour or toHour fields with a value (null is accepted), as it is a request for a full day off.

Shift request must have from and to hour

The SHIFT type does not include the fromHour or toHour fields, which are mandatory for this type of request.

400 Bad Request

The request body is not valid JSON or one of its fields does not have the expected format.

error.request_out_of_service_association

The request period does not match any of the employee’s current service associations.

error.request_out_of_period

The request falls outside the period editable by the current user.

error.request_duplicated_concepts

A request with the same concept already exists in that period.

error.request_overlapped_concepts

The request overlaps with another one of an incompatible concept.

error.person_request_not_allowed_for_day_type

The configured day type does not accept this type of request.

error.person_request_weekly_limit_exceeded

The weekly limit of requests of this type has been exceeded.

Useful links

What is a request?