Users

DronaHQ Plugin REST API provide read/write access to DronaHQ user(s) through the following action(s)-

Get all users

This API returns a list of users within the scope of the tokenkey, ordered chronologically.

ENDPOINT

GET /users

REQUEST PARAMETERS

Query string

Parameter Value Type Description
tokenkey string Required. Your API key. Check authentication for more details
ulimit integer Optional. The number of users to return. Default is 25.
maxuid integer Optional. If given, users with user id greater than the maxuid are returned. To use this argument for paging, you can use the user_id field in the returned user objects.
gid integer Optional. If given, users who belong to the group with id gid are returned.
search string Optional. Keyword to search for in user’s name. Only users matching with the query will be returned.
showstats boolean Optional. If true, a summary of user’s stats will be returned.
listtype string Optional. A enum with 3 possible values. active, inactive, moderate. If active, users with activity status as only “active” are returned.

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object.

On success, the HTTP status code in the response header is 200 OK and the response body contains a list of user object.

User object

Parameter Value Type Description
user_id integer Unique id of the user
user_name string Full name of the user
user_email string Email-id of the user
user_desg string Designation of the user
user_image_url string Profile image url of the user
channel_name string Unique name of account where user is registered in
app_name string Display name of the account where user is registered in
user_reg_date string Registration date of the user in ‘yyyy-MM-dd hh:mm:ss’ format in UTC time-zone
external_idp boolean true if user account is connected to a third-party identity provider
external_idp_response string Response recieved from the third-party identity provider
is_admin boolean true if the user is an admin
user_group array Array of groups which are assigned to the user

Get user

This API returns a user object for the provided userId or Email within the scope of the tokenkey.

ENDPOINT

GET /users/{userIdORuserEmail}

REQUEST PARAMETERS

Url segment

Parameter Value Type Description
userIdORuserEmail string Required. The “user id” or “email id” of the user whose profile information you which to retrieve

Query string

Parameter Value Type Description
tokenkey string Required. Your API key. Check authentication for more details
nonce string Optional. Recieved as SSO parameter from the container app via the dronahq.js
stats boolean Optional. If true, a summary of user’s CMS activity will be returned in the response object.

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object

On success, the HTTP status code in the response header is 200 OK and the response body contains user object.

User object

Parameter Value Type Description
user_id integer Unique id of the user
user_name string Full name of the user
user_email string Email-id of the user
user_desg string Designation of the user
user_image_url string Profile image url of the user
channel_name string Unique name of account where user is registered in
app_name string Display name of the account where user is registered in
user_reg_date string Registration date of the user in ‘yyyy-MM-dd hh:mm:ss’ format in UTC time-zone
external_idp boolean true if user account is connected to a third-party identity provider
external_idp_response string Response recieved from the third-party identity provider
is_admin boolean true if the user is an admin
user_group array Array of groups which are assigned to the user

Create users

This API creates a user account with pre-registered password and group(s) based on the scope of the tokenkey.

ENDPOINT

POST /users

REQUEST PARAMETERS

Request body data

Parameter Value Type Description
token_key string Required. Your API key. Check authentication for more details
pre_register bool Required. Set value to true
invitee_user array Required. An array of the invitee object. A maximum of 50 users can be sent in one request.

Invitee object data

Parameter Value Type Description
user_name string Required. Full name of the invitee
user_email string Required. Email-id of the invitee
user_group_name array Required. A string array of the group-names
user_password string Required. Password for the invitee

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object

On success, the HTTP status code in the response header is 200 OK and the response body contains an empty array.

However, even when the HTTP status code in the response header is 200 OK, pre-registration of few/all invitee might fail.

In such cases the response body would contain an array of the error object of an invitee whose registration failed.

Error object of an invitee

Parameter Value Type Description
user_email string Email-id of the invitee
error_code string Error code
error_detail string Detailed description of the error

Possible error codes

Code Description
2 Email-id is not in correct format.
3 User already exists in the account.
4 The user was registered to atleast one of the mentioned groups but failed for a few.
5 The user could not be registered to any of the mentioned groups. In this case user will not be added to the channel.
6 User license expired. Contact our support desk for more detail.

Assign group(s) to a user

This API can be used to assign a list of groups to a user and can also be used to removes a list of groups assigned to a user within the scope of its tokenkey.

ENDPOINT

PUT /users/{userId}/actions/change_group

REQUEST PARAMETER

Url segment

Parameter Value Type Description
userId integer Required. The unique id of the user.

Request body data

Parameter Value Type Description
token_key string Required. Your API key. Check authentication for more details
assign array Optional. An integer array of unique ids of groups to be assigned to the user.
remove array Optional. An integer array of unique ids of groups to be assigned to the user.

Please note that either assign or remove should contain at least one group id in the request body.

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object. On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON object with a list of groups successfully assigned or removed for a user.

-Please note that even when the HTTP status code in the response header is 200 OK, assigning or removing groups for a user might fail for other reasons such as the group is not a valid group, the API failed to perform the operation. In such cases, the response body would contain an array of the invalid groups in the invalid_groups field and an array of groups for whom the API operation failed in the failed_groups field.

Success response data

Parameter Value Type Description
user_id integer The unique id of the user.
assigned_to array An integer array of unique group ids to which the user was successfully assigned.
removed_from array An integer array of unique group ids from where the user was successfully removed.
invalid_groups array An integer array of unique group ids that are not valid.
failed_groups array An integer array of unique id of groups on which the operation of assigning/removing failed. Retry again with these groups, if problem persists contact our support desk.

Activate Users

This API activates registered users based on the scope of the tokenkey.

ENDPOINT

PUT /users

REQUEST PARAMETER

Request Body Data

Parameter Value Type Description
token_key string Required. Your API key. Check authentication for more details
list_user_email array Required. A string array of the users email. A maximum of 50 IDs can be sent in one request.

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object. On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON object.

Success Response Data

Parameter Value Type Description
users_success integer A string array of user email whose account has been successfully activated.
users_invalid array A string array of invalid user email.
users_not_found array A string array of user not found in the API key scope.
users_failed array A string array of user email on which the operation of activation failed.

Deactivate Users

This API deactivates users based on the scope of the tokenkey.

ENDPOINT

DELETE /users

REQUEST PARAMETER

Request Body Data

Parameter Value Type Description
token_key string Required. Your API key. Check authentication for more details
list_user_email array Required. A string array of the users email. A maximum of 50 IDs can be sent in one request.

RESPONSE FORMAT

On error, the header status code is an error code and the response body contains an error object. On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON object.

Success Response Data

Parameter Value Type Description
users_success integer A string array of user email whose account has been successfully deactivated.
users_invalid array A string array of invalid user email.
users_not_found array A string array of user not found in the API key scope.
users_failed array A string array of user email on which the operation of deactivation failed.