Get eligible employees for a vacancy

This endpoint allows checking, before creating a vacancy, which employees are compatible with the specified requirements and would therefore be eligible to cover it.

POST /api/v1/businesses/{businessId}/vacancies/eligible-employees

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "product": "string",
  "day": "yyyy-MM-dd",
  "shifts": [
    {
      "start": "yyyy-MM-ddTHH:mm:ssXXX",
      "end": "yyyy-MM-ddTHH:mm:ssXXX"
    }
  ],
  "publishToSiblings": false
}
Details

  • product*: external identifier of the product linked to the vacancy.

  • day*: day of the vacancy in yyyy-MM-dd format.

  • shifts*: list of proposed shifts for the vacancy. Includes, for each interval, the following fields:

    • start*: start of the shift in yyyy-MM-ddTHH:mm:ssXXX format. Time zone must be specified as an offset (for example, +02:00) or Z (UTC).

    • end*: end of the shift in yyyy-MM-ddTHH:mm:ssXXX format. Time zone must be specified as an offset (for example, +02:00) or Z (UTC).

  • publishToSiblings: if true, evaluates eligibility also considering employees from sibling products, instead of restricting it only to the specified product. Default is false.

Request example

Once the analysis of the different fields has been done, an example of the request body is shown:

{
  "product": "0001-G",
  "day": "2026-07-25",
  "shifts": [
    {
      "start": "2026-07-25T10:00:00Z",
      "end": "2026-07-25T17:00:00Z"
    }
  ],
  "publishToSiblings": false
}

Response example

{
  "employees": [
    {
      "employeeId": "1006355",
      "fullyEligible": true
    },
    {
      "employeeId": "1006356",
      "fullyEligible": false
    }
  ]
}
Details

  • employeeId: external identifier of the evaluated employee. If not configured in the system, this field will not appear in the response.

  • fullyEligible: if true, the employee has no impediment to cover the vacancy; if false, they have some conflict (for example, overlap or another restriction).

Considerations

Employees who have assignments overlapping with the vacancy, a day off, or incidents on the vacancy date are excluded from the response.

"fullyEligible": true is returned even if the employee’s configured availability is not compatible with the vacancy. For example: if for the vacancy day the employee has "Not available" defined in the availability of their service association, they will still be eligible as long as they meet the rest of the requirements.

"fullyEligible": false is returned if any of these conditions occur:

  • The employee has a cession or regular cession on the vacancy day.

  • The employee fails to meet any of their restrictions, for example, maximum shift duration or rest after worked time.

This query does not create any vacancy, it only evaluates the eligibility of employees for a vacancy that does not yet exist.

Error codes

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

Code Message Description

400 Bad Request

Product is required

The product field is missing.

Day is required

The day field is missing.

Useful links

What is a vacancy?

How to register a vacancy?