Check 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

If any of the mandatory fields is not sent, the request will return a 400 Bad Request error indicating in the message which required field is missing.

If the product for which the vacancy is published does not exist, the request will return a 404 Not Found error indicating in the message not exists.

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.

Useful links

What is a vacancy?

How to register a vacancy?