Add a vacancy

This endpoint allows creating a vacancy and making it public for the employees specified in the request.

POST /api/v1/businesses/{businessId}/vacancies

Mandatory fields are marked with an asterisk (*).

Request body

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

  • id*: external identifier of the vacancy.

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

  • day*: day for which the vacancy is published, in yyyy-MM-dd format.

  • expiration*: deadline for applying to the vacancy. Once this date has passed, applications for the vacancy will no longer be accepted. Must be sent in yyyy-MM-ddTHH:mm:ssXXX format, with time zone as an offset (+02:00) or Z for UTC. Cannot be earlier than the current date and time.

  • employees*: list of external identifiers of the employees who will be notified of the vacancy publication.

  • shifts*: list of shifts defined for the vacancy (1 or 2 maximum). 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). Must match the date the vacancy is published for.

    • 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). Can be later than the date the vacancy is published for, for example, in shifts ending after 00:00.

  • publishToSiblings: determines whether the vacancy is also offered to employees belonging to the same organizational node (true), instead of being restricted 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:

{
  "id": "2f14p",
  "product": "0001-G",
  "day": "2026-07-24",
  "expiration": "2026-07-23T04:00:00Z",
  "employees": [
    "1006370","2677189"
  ],
  "shifts": [
    {
      "start": "2026-07-24T18:00:00Z",
      "end": "2026-07-24T19:00:00Z"
    },
    {
      "start": "2026-07-24T21:00:00Z",
      "end": "2026-07-25T03:00:00Z"
    }
  ],
  "publishToSiblings": true
}

If the data is correct, the vacancy will be published and will be visible under Scheduling > Vacant offers.

Considerations

Shifts (shifts) must match the day the vacancy is published for (day). The end field can be later in shifts ending after 00:00.

Times must be sent in UTC or with the corresponding time zone, and the publication is done considering the service’s time zone.

Overlap with other existing vacancies or assignments on the same day and shift is not validated — only incidences (above) and, if applicable, the product membership are checked.

Siblings of a product are the other products that belong to the same node in the organizational structure.

Different vacancies can be published for the same date and interval as long as the external identifiers do not match.

Error codes

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

Code Message Description

400 Bad Request

Id is required / Product is required / Day is required / Expiration is required / Employee ids are required

One of the mandatory fields is missing.

Employee ids cannot be empty

The employees field is empty.

Expiration can not be before now

The expiration date is earlier than the current moment.

Shifts must be less or equal than 2

More than two shifts have been specified.

Start is required / End is required / Start must be after day / End must be after day / Start date for a Shift must be included in the day / End date for a Shift must be included in the day or in the next day / Shift has a wrong date range

One of the shifts (shifts) does not meet the expected format or range with respect to day.

Employees do not belong to product <id>: [ids]

With "publishToSiblings": false, one of the specified employees does not belong to the vacancy’s product.

Vacancy already exists

The external identifier (id) is already in use by another vacancy.

Any of the employees has an incidence overlapping with the vacancy

One of the specified employees has an incidence that overlaps with the vacancy.

Useful links

What is a vacancy?