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, the response will contain the information linked to the user: username, email, nodes and roles, with 200 OK if the user already existed or 201 Created (with a Location header) if it has been created.

Considerations

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

Only nodes belonging to the business of the request can be added. The nodes in nodes that do not belong to this business are silently discarded (without an error): if none remain after filtering them out, or if the field is not sent, the user is automatically assigned the root node of the business instead of being left without nodes.

For roles, the role name must exactly match the one configured in the system under Business configuration > Roles.

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.

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

Error codes

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

Code Message Description

400 Bad Request

-

The username in the URL does not match the one in the request body.

error.user_validation. [Nodes cannot be null]

The nodes field is missing.

error.user_validation. [Nodes cannot be empty]

The nodes field is empty.

error.user_validation. [User username cannot be null]

The username field is missing.

error.user_validation. [User email cannot be empty]

The email field is missing.

User email is not valid

The email format is not valid (basic validation).

error.node_not_found. [id]

One of the nodes identifiers does not exist in Orquest.

error.role_not_found. [role]

One of the roles does not match those defined at the business level.

error.email_already_exists. [email]

The email already belongs to another registered user.

User not found. []

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

409 Conflict

Some role is not valid

One of the user’s roles (those in user.roles, not those in the service associations) is not valid.

This endpoint has its own error handling that does not follow the general API format: the 401 Forbidden from the common catalog, and the 401 Service or node forbidden when the node exists but is outside the visibility of the requester, are returned here as 400/404 with no body depending on the case, instead of the usual 401 with a message. Only 401 Business forbidden (non-existent business) keeps the standard format.

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?