Groups

Retrieve list of groups

GET /api/v1/tenants/(string: tenant_id)/groups/

List the groups known in the tenant.

In case of reseller user and the reseller check on Tenant or Group level is enabled (see below) only the Groups owned by his Reseller will be returned.

Example request:

GET /api/v1/tenants/foo/groups/ HTTP/1.1
Host: example.com

{
   "sensitiveGroupNameContains": "Test"
}

GET /api/v1/tenants/foo/groups/ HTTP/1.1
Host: example.com

{
   "sensitiveGroupNameContains": "Test",
   "pagingControl" : {
      "startIndex" : 1,
      "pageSize" : 2
   },
   "sortOrders": ["sensitiveDescendingGroupName", "sensitiveDescendingGroupId"]
}
Request JSON Object:

  • sensitiveGroupIdStarts (string) – (Optional) See sensitiveGroupIdStarts from Search criteria.

  • sensitiveGroupIdContains (string) – (Optional) See sensitiveGroupIdContains from Search criteria.

  • sensitiveGroupIdEquals (string) – (Optional) See sensitiveGroupIdEquals from Search criteria.

  • insensitiveGroupIdStarts (string) – (Optional) See insensitiveGroupIdStarts from Search criteria.

  • insensitiveGroupIdContains (string) – (Optional) See insensitiveGroupIdContains from Search criteria.

  • insensitiveGroupIdEquals (string) – (Optional) See insensitiveGroupIdEquals from Search criteria.

  • sensitiveGroupNameStarts (string) – (Optional) See sensitiveGroupNameStarts from Search criteria.

  • sensitiveGroupNameContains (string) – (Optional) See sensitiveGroupNameContains from Search criteria.

  • sensitiveGroupNameEquals (string) – (Optional) See sensitiveGroupNameEquals from Search criteria.

  • insensitiveGroupNameStarts (string) – (Optional) See insensitiveGroupNameStarts from Search criteria.

  • insensitiveGroupNameContains (string) – (Optional) See insensitiveGroupNameContains from Search criteria.

  • insensitiveGroupNameEquals (string) – (Optional) See insensitiveGroupNameEquals from Search criteria.

  • responseSizeLimit (integer) – (Optional) See responseSizeLimit from Search criteria.

  • pagingControl (object) – (Optional) See pagingControl from Paging Control elements. If pagingControl is provided, responseSizeLimit will be ignored.

  • sortOrders (array) – (Optional) See sortOrders from Paging Control elements. Maximum 3 elements in the list. Possible field names are : “GroupName” and “GroupId”. Default is “insensitiveAscendingGroupId”.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "groups": [
      {
         "groupId": "foogroup",
         "groupName": "Foo Group",
         "userLimit": 10
      }
   ]
}
Response JSON Object:
Status Codes:

Create a group

POST /api/v1/tenants/(string: tenant_id)/groups/

Create a new group in the tenant.

Note that a reseller user is not allowed to create a Tenant if RESELLER_GROUP is enabled.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "groupId": "foogroup_new",
   "groupName": "Foo Group New",
   "userLimit": 25
}
Request JSON Object:

  • groupId (string) – See groupId from Group attributes.

  • groupName (string) – See groupName from Group attributes.

  • userLimit (integer) – See userLimit from Group attributes.

  • defaultDomain (string) – See defaultDomain from Group attributes.

  • cliName (string) – See cliName from Group attributes.

  • cliPhoneNumber (string) – See cliName from Group attributes.

  • locationDialingCode (string) – See cliName from Group attributes.

  • timeZone (string) – See timeZone from Group attributes.

  • contactInformation (object) – See contactInformation from Group attributes.

  • addressInformation (object) – See addressInformation from Group attributes.

  • resellerId (string) – See resellerId from Group attributes. If not present and the corresponding Tenant has a Reseller, that one will be used.

  • templateName (optional) (string) – The name of the template to be used during the Group creation.

  • autoCreateDomain (boolean) – If the defaultDomain provided does not exist, will be created at System and Tenant level and assigned to the Group.

Example response:

Response JSON Object:
Status Codes:

Configuration Information for default domain Auto Creation

The APIO behaviour is controlled by the following settings:

"AUTO_CREATE": {
                    "GROUP_DEFAULT_DOMAIN": true
               }
With following parameter:

  • AUTO_CREATE.GROUP_DEFAULT_DOMAIN: If true, if the defaultDomain provided does not exist, will be created at System and Tenant level and assigned to the Group. The behaviour can be overriden by the autoCreateDomain parameter within the input data.

Template Information for Group

The template category is group

Configuration Information for Group Creation

In the POST API, the APIO can create a GroupData object and can also auto-create a Reseller object with as name the resellerId if not existing.

The following settings is to instruct the APIO how to manage this:

"APIO_OBJECT_CREATION": {
    "GROUP_DATA": true,
    "RESELLER": true
},
"DEFAULT_TEMPLATES": {
   "GROUP_CREATE": "default_grp_template",
},
Settings description:

  • APIO_OBJECT_CREATION: is a set of settings for controlling the auto-creation of different objects in APIO DB.

  • RESELLER if true, if a resellerId is received and the corresponding Reseller does not exist it will be created; if false in same conditions it will be rejected. Default is False.

  • GROUP_DATA if true, a GroupData object will be created when creating a new Group. Note that if a resellerId is provided, a GroupData object will be created in all cases.

  • DEFAULT_TEMPLATES: is a set of settings for defining a default provisioning template for some operations. None are defined by default.

  • GROUP_CREATE: the default template for Group create operation. It must of course be of the template category group.

Configuration Information for Groups List

In the GET API, in case of reseller the APIO checks the TenantData and GroupData objects if the following settings is enable:

"RESELLER_GROUP": true,
"RESELLER_TENANT": true,
Settings description:

  • RESELLER_GROUP if true and the user is a reseller, the reseller check at Group level is enabled. For this API it means that the GroupData objects are checked to returns only the groups beloging to the same Reseller.

  • RESELLER_TENANT if true and the user is a reseller, the reseller check at Tenant level is enabled. For this API it means that the TenantData objects are checked to returns only the tenants beloging to the same Reseller and therefore also the Groups inside that tenant.