Add an employee role

This endpoint allows adding a new employee role within a service or store.

POST /api/v1/businesses/{businessId}/services/{serviceId}/employee-role

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

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "id": "string",
  "orquestId": 0,
  "name": "string",
  "color": "string"
}
Details

  • id*: external identifier of the employee role. Must be unique.

  • orquestId: internal identifier of the role in Orquest. It is not necessary to send it, as the system will add it automatically.

  • name*: name of the role.

  • color*: hexadecimal color code that must match the regular expression "^(#[A-Fa-f0-9]{6})$".

Request example

After analyzing the various fields, an example of the request is shown:

POST /api/v1/businesses/BUSINESSID/services/0001/employee-role
{
  "id": "ID001",
  "name": "Manager",
  "color": "#921b01"
}

If all the data is correct, a role with the specified characteristics will be created, which can be applied to any employee associated with this service.

Considerations

If the service does not exist, the request will return a 404 Not Found error indicating not exists.

If the external identifier is duplicated, the request will return 400 Bad Request indicating an error with the outer_id.

If the color is not in hexadecimal code, the request will return a 406 Not Acceptable error indicating must match \"^(#[A-Fa-f0-9]{6})$\".

Once the role is created, it can be applied to a service or store employee in two ways:

  • Manually: by editing the employee’s store association within the Orquest interface.

  • Via API: using the complex endpoints for creating or updating employee or employee list. It will be necessary to include the roles field within the serviceAssociations object with the identifier of the role you want to apply to the employee.

Example 
[
  {
    "business": "BUSINESSID",
    "lag": 0,
    "person": {
      "name": "John",
      "surname": "Carmack",
      "employeeId": "000000"
      },
    "serviceAssociations": [
      {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-10-01",
        "to": null,
        "roles": [
          "ID001"
        ]
      }
    ]
  }
]

Since the employee role has been created in service 0001, it can be applied within an association to this same service.

Useful links

What is an employee role?