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

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 external identifier of the vacancy already exists, the request will return a 400 Bad request error indicating Vacancy already exists.

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.

If "publishToSiblings": false is sent, it is validated that all employees listed in the request belong to the product where the vacancy is published. If any of them do not belong to that product, the request will return a 400 Bad Request error with the message Employees do not belong to product.

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.

Useful links

What is a vacancy?