Create and edit user account

Introduction

This guide will demonstrate to developers the process of programmatically creating and editing user accounts using the API.

Initially, we'll delve into the distinctions between inviting a new user to the organization versus creating an active user. Subsequently, we'll update a user's information and reassign them to a different group.

Requirements

• active admin account

  

  Read more in user guide - User administration

• ID of the group(s) the user will join

1. Invite new user to your organization

In this scenario, we'll create a user profile and forward the activation email to the user. The recipient must then activate their account using the link provided in the email.

Step 1 - Retrieve Organization ID

In order to assign user to an organization and group, we must first determine their IDs because the display name isn't a unique identifier. To initiate this, we must obtain the organization ID, which we get by extracting information about any member of the organization.

Read more about fetching user info - Retrieve user info

Lets fetch the info from our account:

Endpoint

GET /users/:id

Request

GET /users/john.doe@circularo.com?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY

Response

{
  ...
  "team": "cce730c3-1123-4ae8-855d-92f074358227"
}

Note following properties in response object:

• organizationId - In response object at position team.

  • It may have value of cce730c3-1123-4ae8-855d-92f074358227.

Step 2 - Obtain Group ID

Upon determining our organization's ID, we can find out internal group IDs. The essential information we require is nested in the teamGroups object:

Endpoint

GET /groups/:organizationId

Request

GET /groups/cce730c3-1123-4ae8-855d-92f074358227?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY

Response

{
  "_id": "cce730c3-1123-4ae8-855d-92f074358227",  //Organization ID
  ...
  "name": "cce730c3-1123-4ae8-855d-92f074358227",
  "team": "cce730c3-1123-4ae8-855d-92f074358227",
  "teamGroups": {  //IDs of the different groups according to user role
    "admin": "a8704b80-0ae4-4311-8db5-772c2377fbde",
    "prepare": "2b9f402e-91f1-433c-98e1-768b9758383d",
    "read": "e0713c7d-5288-4e58-97ed-1f0a8f2ad562",
    "sign": "46e2f0ff-b430-40ee-937f-61a33656e47f",
    "user": "3da19e21-97e8-4e6e-8b1f-46291509fef4"
  },
  "type": [
    "team"
  ]
}

Note following properties in response object:

• adminGroupId - In response object at position teamGroups.admin.

  • This is user group for admin users.

  • It may have value of a8704b80-0ae4-4311-8db5-772c2377fbde.

• prepareGroupId - In response object at position teamGroups.prepare.

  • This is user group for lite users who have prepare only rights.

  • It may have value of 2b9f402e-91f1-433c-98e1-768b9758383d.

• readGroupId - In response object at position teamGroups.read.

  • This is user group for lite users who have read only rights.

  • It may have value of e0713c7d-5288-4e58-97ed-1f0a8f2ad562.

• signGroupId - In response object at position teamGroups.sign.

  • This is user group for lite users who have sign only rights.

  • It may have value of 46e2f0ff-b430-40ee-937f-61a33656e47f.

• userGroupId - In response object at position teamGroups.user.

  • This is user group for regular users.

  • It may have value of 3da19e21-97e8-4e6e-8b1f-46291509fef4.

Step 3A - User Invitation

Now that we've obtained both the organization and group IDs, we can proceed to invite a new member to our organization. He will have regular user role so we need to add him to our organization and set him to user group.

Endpoint

POST /users

Request

POST /users?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY

Content-Type: application/json

{
  "sendMail": true,  //Use 'false' to not send an invitation email
  "users": [
    {
      "fullname": "Derek Edward Trotter",
      "mail": "api.test@circularo.com",
      "name": "api.test@circularo.com",
      "group": [  //Both organization and user group IDs
        "cce730c3-1123-4ae8-855d-92f074358227",  //Organization ID
        "3da19e21-97e8-4e6e-8b1f-46291509fef4"  //Regular user group
      ],
      "team": "cce730c3-1123-4ae8-855d-92f074358227",  //Organization ID
      "status": "newly_created"
    }
  ]
}

Notes:

• If status is newly_created it is recommended to keep sendMail: true to ensure the user gets an invitation email and can activate their account.

• Status newly_created is visible as “Invited” in Circularo

Response

{
  "errors": false,
  "count": 1,
  "items": []
}

The user is now created in our organization and received an invitation email. Once the user finalizes the activation, they'll gain access to Circularo.

Step 3B - Create an active user

Here, our goal is to generate an active user profile within our organization. No activation email is dispatched, and a password is pre-configured.

This method is particularly suited for organizations that prefer their IT departments to set up accounts and convey login details via alternate communication methods.

Endpoint

POST /users

Request

POST /users?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY

Content-Type: application/json

{
  "sendMail": false,  //user will not be notified
  "users": [
    {
      "fullname": "Derek Edward Trotter",
      "mail": "api.test@circularo.com",
      "name": "api.test@circularo.com",
      "password": "#del.boy!",
      "group": [  //Both organization and user group IDs
        "cce730c3-1123-4ae8-855d-92f074358227",  //Organization ID
        "3da19e21-97e8-4e6e-8b1f-46291509fef4"  //Regular user group
      ],
      "team": "cce730c3-1123-4ae8-855d-92f074358227",  //Organization ID
      "status": "active"  //Set account to active state
    }
  ]
}

Notes:

• "sendMail": false - the user won't receive any activation notice regarding the creation of their Circularo account.

• Password - A password must be provided for active users within the request.

• Status - The status should be set to active

Response

{
  "errors": false,
  "count": 1,
  "items": []
}

Upon successful creation, the user's credentials can be communicated to the user.

2. Modifying User Information and Group Assignment

After adding a user into our organization, we possess the capability to alter their details and move them between groups. For illustrative purposes, we'll move the user to a read-only group and edit their contact number.

Step 4 - Group Removal

Before adding the user to a new group, it's essential to remove them from their current regular user group.

Endpoint

POST /users/:id/removeFromGroup

Query parameters:

• groupname - Group ID of the group that you want to remove user from (in our case 3da19e21-97e8-4e6e-8b1f-46291509fef4).

Request

POST /users/api.test@circularo.com/removeFromGroup?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY&groupname=3da19e21-97e8-4e6e-8b1f-46291509fef4

Response

{
  "status": "SUCCESS"
}

User is now removed from the regular users group.

Step 5 - Add user to group

Now we can add the user to our desired group which will be read-only.

Process is the same, only endpoint changes.

Endpoint

POST /users/:id/addToGroup

Query parameters:

• groupname - Group ID of the group that you want to add user to (in our case e0713c7d-5288-4e58-97ed-1f0a8f2ad562).

Request

POST /users/api.test@circularo.com/addToGroup?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY&groupname=e0713c7d-5288-4e58-97ed-1f0a8f2ad562

Response

{
  "status": "SUCCESS"
}

User now has read-only rights.

Step 6 - Edit user info

Lets finish our scenario by changing user's phone number in his personal info.

Endpoint

PUT /users/:id

Request

PUT /users/api.test@circularo.com?token=acJvct6xo9TbAZMbcQIYUYGUTEqBKf2xfplYUZOe1ht1RxwtvOzZQkhMoahzSoFY

Content-Type: application/json

{
  "phone": "+420777888999"
}

Response

{
  "status": "SUCCESS"
}

Once the modifications are saved, retrieving the user's data will display the updated contact number and the user can see the change in his Circularo profile: