Create or update user

This endpoint allows adding or updating user information within the business.

PUT /api/v2/businesses/{businessId}/users/{username}

Below is a detailed explanation of each field that may be part of the request body, with some being mandatory for a successful request.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "username": "string",
  "email": "string",
  "nodes": [
    0
  ],
  "roles": [
    "string"
  ]
}
Details

  • username*: username. Must be unique. Typically, an email address is used.

  • email*: email address in a correct format. Must be unique.

  • nodes*: list of internal Orquest node identifiers where the user will have visibility.

  • roles: list of roles assigned to the user.

Request example

After analyzing the various fields, here’s an example of the request:

PUT /api/v2/businesses/BUSINESSID/users/test.user@orquest.com
{
    "username": "test.user@orquest.com",
    "email": "test.user@orquest.com",
    "nodes": [
        5391, 5392
    ],
    "roles": ["Manager"]
}

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

Considerations

If the username provided as a parameter in the URL does not match the one specified in the username field, the request will return a 400 Bad Request error.

If an attempt is made to link a user to an email already associated with a registered user, the request will return a 400 Bad Request error with the message error.email_already_exists. [email].

The email address linked to a user can be updated; simply specify the updated email in the request body.

If the email format is invalid, the request will return a 400 Bad Request error with the message User email is not valid.

For nodes, specify the internal node identifiers in Orquest. If no identifier is included, the request will return a 400 Bad Request error with the message Nodes cannot be null.

An integration user will be able to assign any role defined at the business level.

For roles, the role name must exactly match the one configured in the system under Business configuration > Roles. If any roles do not match those defined in the business configuration, the request will return a 400 Bad Request error with the message error.role_not_found. [role].

If any roles were previously defined for the user, this information must also be sent in the update. If the field is not sent, is set to null, or an empty array [] is sent, all roles will be removed.

Useful links

What is a user?

What is a node? How to get business nodes?

What is the difference between an employee role and a user role?