Usergroups¶

URLs¶

http://example.com/api/usergroups—refer to all user groups. Supports GET and POST.
http://example.com/api/usergroups/:id—refer to a particular user group. Supports GET, PUT, and DELETE.
http://example.com/api/users/:id/usergroups/—refer to the user groups that the specified user belongs to. Supports GET.
http://example.com/api/users/:id/usergroups/:id—refer to a particular user group that the specified user belongs to. Supports PUT and DELETE.

Important

Usergroup IDs 1 and 2 are reserved for Guests and Registered users respectively. These groups don’t show up, unless you refer to them directly. You can’t delete or modify these groups.

Filtering¶

Use the following parameters to find user groups with specific properties.

Parameter	Description
type	Show user groups of specific type: `A`—administrator group `C`—customer group
status	Show user groups with specific status: `A`—active `H`—hidden `D`—disabled

Examples:

http://example.com/api/usergroups?status=A

Response is an array with all active user groups.

http://example.com/api/users?status=D&type=C

Response is an array with all customer groups with the Disabled status.

Fields¶

A user group has a number of properties, represented by fields.

The full list of supported fields is given below (mandatory fields are marked with *).

Note

Any field not listed in the table below will be ignored if occurs in an API request JSON data.

Field name	Description	Available for methods	Supported values
usergroup_id	The ID of the user group.	`GET`	integer
type*	The type of the user group.	`GET` `POST` `PUT`	`A`—admins `C`—customers
status*	The status of the user group.	`GET` `POST` `PUT`	`A`—active `H`—hidden `D`—disabled
usergroup	The name of the user group.	`GET` `POST` `PUT`	string
privileges	The privileges of the members of this group. This only applies to administrator groups.	`GET`	array

Example Usage¶

GET /usergroups/¶

curl -X GET 'http://example.com/api/usergroups'

This example request returns the list of user groups.

GET /usergroups/:id¶

curl -X GET 'http://example.com/api/usergroups/3'

This example request returns the properties of the user group with the usergroup_id=3.

POST /usergroups/¶

Send the data in the body of the HTTP request. The data should comply with the content-type.

If you successfully create a user group, you will receive HTTP/1.1 201 Created.

If the user group couldn’t be created, you will receive HTTP/1.1 400 Bad Request.

Required fields: type, status

Available fields: status, type, usergroup

curl --header 'Content-type: text/plain' -X POST 'http://example.com/api/usergroups' --data-binary 'type=A&status=D&usergroup=Managers'

This example request creates a new administrator group called Managers. The status of the user group is set to Disabled.

In the response you receive the ID of the user group.

{usergroup_id: 5}

PUT /usergroups/:id/¶

Send the data in the body of the HTTP request. The data should comply with the content-type.

Required fields: type, status

Available fields: status, type, usergroup

curl --header 'Content-type: text/plain' -X PUT 'http://example.com/api/usergroups/5' --data-binary 'type=A&status=A'

This example request sets the status of the user group with usergroup_id=5 (Managers in our case) to Active.

In the response you receive the ID of the user group.

{usergroup_id: 5}

DELETE /usergroups/:id¶

If you successfully delete a user group, you will receive HTTP/1.1 204 No Content.

If the user group couldn’t be deleted, you will receive HTTP/1.1 400 Bad Request.

If the user group doesn’t exist, you will receive HTTP/1.1 404 Not Found.

curl -X DELETE 'http://example.com/api/usergroups/5'

This example request deletes the user group with the usergroup_id=5.

Users and User Groups¶

View User’s Groups¶

Let’s see what status a user with a user_id=3 has in various user groups.

curl -X GET 'http://example.com/api/users/3/usergroups'

In response you will receive arrays with usergroup IDs and the statuses of the user in those groups.

Important

The request won’t return the groups that have the Available status for that user.

Parameter	Description
link_id	The ID of the link that assigns the user to the group.
usergroup_id	The ID of the user group.
status	The status of the user in the group: `A`—active—the user is a part of the group `F`—available—the user is not a part of the group `P`—pending—the customer has requested to join the group `D`—declined—the customer’s request to join the group has been declined

Change User’s Status in a Group¶

If you want to add a user to a group, change the user’s status in the group to Active. Let’s add the user with user_id=3 to the user group with usergroup_id=5.

curl --header 'Content-type: text/plain' -X PUT 'http://example.com/api/users/3/usergroups/5' --data-binary 'status=A'

This request adds the user to the specified group and sets the status to Active. You should receive the following message: Status has been changed.

If the user couldn’t be added to the group you will receive HTTP/1.1 400 Bad Request.

Hint

You may receive error 400 if the user group with the specified ID doesn’t exist, or if you’re trying to add a customer to an administrator group.

If the user doesn’t exist, you will receive HTTP/1.1 404 Not Found.

Remove User from a Group¶

You can remove user from a group in two ways:

by setting the status of the user in the group to Available:

curl --header 'Content-type: text/plain' -X PUT 'http://example.com/api/users/3/usergroups/5' --data-binary 'status=F'

by using the DELETE method:

curl -X DELETE 'http://example.com/api/users/3/usergroups/5'