POST: Create a user

The POST operation can be used to create both internal, native ValueEdge users or SSO users, and LDAP users.

Contexts in which you can add users

To create a user, perform a POST in one of the following contexts: 

Context Notes
Shared space

Space admin permissions are required.

You can create a shared space user without assigning a role. In this case, the user is created with the predefined viewer role. For an example on assigning roles later using the REST API, see PUT: Update a user's role.

If you do not specify a work space when POSTing the user, the default_workspace is used.
Workspace

Workspace admin permissions are required.

Note: Most roles can be customized. Roles and their permissions might be different for your organization.

You must assign a role when creating a workspace user.

You cannot add users in the site context using the REST API.

Back to top

Creating internal, native or SSO users

Use the following fields when creating a new user:

Field Required Must be unique
uid
name

(used for login)
first_name
last_name
email

If another user exists with the same email address, an error is returned.

Bulk POSTs are supported.

Back to top

Examples

  • Add a single user to the shared space

  • Internal, native ValueEdge user management

Because no workspace is specified in this example, the user is added to default_workspace. 

*** Request ***
POST .../api/shared_spaces/<space_id>/users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123"
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "sharedspace_user",
      "id": "1015"
    }
  ],
  "exceeds_total_count": false
}

Back to top

This example attempts to create two users. However only one is created, because the other user has the same email address as an existing user. Response code 409 is returned, "A site user with this ID already exists."

*** Request ***
POST .../api/shared_spaces/<space_id>/users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123"
    },
 
    {
      "email": "leroy.brown@TheCompany.com",
      "first_name": "leroy",
      "last_name": "brown",
      "name": "Leroy Brown",
      "password": "Welcome1",
      "phone1": "123-356-0123"
    }

  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "sharedspace_user",
      "id": "1018"
    }
  ],
  "exceeds_total_count": false,
  "errors": [
    {
      "index": 0,
      "error_code": "platform.duplicate_entity_error",
      "correlation_id": "md7goq75nzeyquvx77x1g8yzj",
      "description": "A site_user with this email already exists.",
      "description_translated": "A site_user with this email already exists.",
      "properties": {
        "entity_type": "site_user",
        "message": "service=[CreateServiceImpl], blFlowCommand=[SharedspaceUserCreateCommand], token=[SharedspaceUserEntityToken] has thrown an exception and terminated BL flow. See service result log message for details. Error=[A site_user with this email already exists.]",
      "field_name": "email"
      },
    }
  ]
}

Back to top

  • Add a single user to a workspace
  • Internal, native ValueEdge user management

When adding a user to a workspace, make sure to specify a role.

In this example, 1003 refers to the leader role. The PUT: Update a user's role example demonstrates how to get a list of existing roles. 

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/workspace_users
{
  "data": [
    {
      "email": "marta.santora@TheCompany.com",
      "first_name": "marta",
      "last_name": "santora",
      "name": "Marta Santora",
      "password": "Welcome1",
      "phone1": "969-979-9123", 
      "roles": {
        "data": [
          {
            "type": "user_role",
            "id": "1003"
          }
        ]
      }
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "workspace_user",
      "id": "1021"
    }
  ],
  "exceeds_total_count": false
}

  • Add a single user to a workspace

  • LDAP user management

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/workspace_users
{
  "data": [
    {
      "uid": "b5d4a886-2347-435a-8557-e3d8561b5f38",
      "email": "sally.smith@TheCompany.com",
      "first_name": "sally",
      "last_name": "smith",
      "ldap_dn": "cn=Sally.Smith@TheCompany,ou=MyConglomerate,dc=com",
      "ldap_server_id": 1001,
      "name": "sally@TheCompany.com",
      "phone1": "969-979-9123",
      "roles": {
        "data": [
          {
            "type": "user_role",
            "id": "1003"
          }
        ]
      }
    }
  ]
}
*** Response ***
{
  "total_count": 1,
  "data": [
    {
      "type": "workspace_user",
      "id": "1021"
    }
  ],
  "exceeds_total_count": false
}

Back to top

See also: