Link user to an employee

This endpoint allows linking an existing user to an employee within the same business.

PUT /api/v2/businesses/{businessId}/employees/{employeeId}/user

In addition to the external business identifier (businessId), the URL must specify the external identifier of the employee to whom the user will be linked: employeeId. In the request body, only the username of the user already registered in the system is included:

Request body

JSON Analysis 
{
  "username": "string"
}
Details

  • username*: username. Must be unique and already registered in the system. Typically, an email address is used.

Request example

Below is an example of the request:

PUT /api/v2/businesses/BUSINESSID/employees/1006350/user
{
    "username": "test.user@orquest.com"
}

If the request is successful (200 OK), the response will contain the user’s linked information: username, email, nodes, and roles.

Considerations

If there was a previous association with another user or employee, the relationship is updated in accordance with the data defined in the request: the employee’s previous user is unlinked from them, and if the specified user was already linked to another employee, it is also unlinked from that other employee. These are two silent unlinks, without any notice in the response.

Linking is not an isolated operation on the user-employee link: as part of the process, the user’s nodes are recalculated and filtered to those of the business of this request (same behavior as updating a user). If the user had nodes from other businesses, they may lose visibility over them as a side effect of this operation.

Error codes

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

Code Message Description

404 Not Found

-

The employeeId in the URL does not match any employee in the business.

-

The username in the body does not match any user in the business.

-

The username field is missing or arrives as null in the body (the validation of this field is not actually applied — see the note below).

400 Bad Request

User not found. []

The username exists, but registered in another business different from the one in the request.

This endpoint has its own error handling that does not follow the general API format: the three 404 cases above, and the 401 Forbidden/401 Service or node forbidden from the common catalog, are all returned as responses with no body. Only 401 Business forbidden (non-existent business) keeps the standard format with a message.

Useful links

What is a user?

What is an employee?