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

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.

Error codes

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

Code Message Description

400 Bad Request

-

The body of the request is not valid JSON or one of its fields does not have the expected format.

error.outer_id

The external identifier (id) provided is already in use by another role within the same service. Uniqueness is per service, not global to the business.

406 Not Acceptable

must match "^(#[A-Fa-f0-9]{6})$"

The color field does not have the expected hexadecimal format.

Useful links

What is an employee role?