Device groups Resource

Provides access and management of device groups.

GET /{tenantGuid}/api/v1/deviceGroups

Available Since:
12.13.0

Search for device groups.

Samples

Sample 1 request

Get the first 100 device groups sorted by name in ascending order. 

 GET /SRP00000/api/v1/deviceGroups

Sample 1 response body

 
 {
  "deviceGroups": [ {
   "guid" : "6d0c4ddb-10ae-471d-948d-df27868dcf8a",
   "name" : "Test device group name"
  }, {
   "guid" : "6dd3a8e2-3f24-48c6-961a-949794f4b554",
   "name" : "Test device group 2 name"
  } ]
 }

Sample 2 request

Get the first 50 device groups that have a name that starts with "M", sorted by name in descending order. If 50 device groups are returned, there may be more matches that weren't returned. You can get the next "page" of device groups by sending the same request but also specifying offset=50. If 50 device groups are returned again, you can get the third "page" of device groups by modifying the request again and specifying offset=100, and so on. 

 GET /SRP00000/api/v1/deviceGroups?query=name=M*&max=50&sortBy=name%20DESC

Sample 2 response body

 
 {
  "deviceGroups": [ {
   "guid" : "6dd3a8e2-3f24-48c6-961a-949794f4b554",
   "name" : "Mobile iOS group name"
  } ]
 }

Request Parameters
Name Location Description Type
includeTotal query If you want the total number of device groups matching the search included in the response (which may be different from the number of device groups returned) set this to true; otherwise set to false. By default the total will not be included in the response. boolean
max query The maximum number of device groups results to get, between 1 and 1000 inclusive. If not specified, a value of 100 will be used. int
offset query The number of matching device groups to exclude from the beginning of the list of device groups in the response; greater than or equal to 0. If not specified, a value of 0 will be used to indicate that no matches should be excluded. Used in order to get "pages" of results. For example, to get the first 50 matching device groups, specify max=50 (and optionally offset=0); and to get the next 50 matching device groups specify max=50 and offset=50, and so on. int
query query Query parameter for filtering the results. The format is <field name>=<query value>, for example name=Group. Multiple field-value pairs can be provided in the query with each pair separated with a comma, in which case only device groups matching all of the criteria provided will be included in the response. Querying for empty/null values is not supported.

By default, a case-insensitive exact match will be performed for each field in the query. For fields that support prefix (i.e. starts with) matching, append an asterisk ("*") to the end of the value. For example, to find device groups that have a name that start with "G", specify name=G*. To match an asterisk at the end of a string instead of prefix matching, the asterisk must be escaped with a backslash.

Special characters (comma, backslash, plus) in query values must be escaped with a backslash.

The following table describes the fields that can be used in the query.

Field Type Description Supports prefix matching
name string Name of the device group. Yes
guid string GUID of the device group. No
 
sortBy query The field to sort the device groups results by. The format is <field name> ASC|DESC, where ASC means to sort the results in ascending order and DESC means descending order. For example, to sort the results by name in descending order, specify name DESC. If not specified, a value of name ASC will be used. The following fields are allowed: name.  
Response Codes
Code Condition Data type
200 OK (even if no device groups are found).
400 Invalid search query.
Response Body
Media type Data type Description
application/vnd.blackberry.devicegroups-v1+json Device groups (JSON)

POST /{tenantGuid}/api/v1/deviceGroups

Available Since:
12.13.0

Create a device group.

Samples

Sample request body

 
 {
  "name":"Test device group name",
  "queryOperator":"and",
  "query": [ {
    "field": "ACTIVATION_TYPE",
    "operator": "=",
    "value": "FULL_CONTROL_AFW"
  } ]
 }

Sample response body

 
 {
  "guid":"6d0c4ddb-10ae-471d-948d-df27868dcf8a",
  "name":"Test device group name",
  "queryOperator":"and",
  "query": [ {
    "field": "ACTIVATION_TYPE",
    "operator": "=",
    "value": "FULL_CONTROL_AFW"
  } ]
 }

Request Body
Media type Data type
application/vnd.blackberry.devicegroup-v1+json Device group details (JSON)
Response Codes
Code Condition Data type
201 Group created.
400 Invalid request. For example, invalid field semantics or missing required field.
409 Device group already exists.
Response Body
Media type Data type Description
application/vnd.blackberry.devicegroup-v1+json Device group details (JSON)
Response Headers
Name Description
Location Location of the created device group. Can be used to perform a GET request to retrieve the device group. Only present when status is 201.

DELETE /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}

Available Since:
12.13.0

Delete a device group.

Request Parameters
Name Location Description
deviceGroupGuid path GUID of the device group to delete.
Response Codes
Code Condition Data type
204 Device group deleted.
    400 Invalid request. For example, invalid field semantics or missing required field.
    404 Device group not found.

    GET /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}

    Available Since:
    12.13.0

    Get device group by a specific GUID.

    Sample response body

     
 {
  "guid":"6d0c4ddb-10ae-471d-948d-df27868dcf8a",
  "name":"Test device group name",
  "queryOperator": "and",
  "query": [ {
    "field": "ACTIVATION_TYPE",
    "operator": "=",
    "value": "FULL_CONTROL_AFW"
  } ]
 }

    Request Parameters
    Name Location Description
    deviceGroupGuid path GUID of the device group to get
    Response Codes
    Code Condition Data type
    200 OK.
    404 Device group not found.
    Response Body
    Media type Data type Description
    application/vnd.blackberry.devicegroup-v1+json Device group details (JSON)

    PUT /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}

    Available Since:
    12.13.0

    Update a device group.

    Samples

    Sample request body

     
 {
  "name":"Test device group name",
  "queryOperator":"and",
  "query": [ {
   "field": "ACTIVATION_TYPE",
   "operator": "=",
    "value": "FULL_CONTROL_AFW"
  } ]
 }

    Sample response body

     
 {
  "guid":"6d0c4ddb-10ae-471d-948d-df27868dcf8a",
  "name":"Test device group name",
  "queryOperator":"and",
  "query": [ {
    "field": "ACTIVATION_TYPE",
    "operator": "=",
    "value": "FULL_CONTROL_AFW"
  } ]
 }

    Request Parameters
    Name Location Description
    deviceGroupGuid path
    Request Body
    Media type Data type
    application/vnd.blackberry.devicegroup-v1+json Device group details (JSON)
    Response Codes
    Code Condition Data type
    200 Device group updated.
    400 Invalid request. For example, invalid field semantics or missing required field.
    404 Device group not found.
    409 Device group already exists.
    Response Body
    Media type Data type Description
    application/vnd.blackberry.devicegroup-v1+json Device group details (JSON)
    Response Headers
    Name Description
    Location Location of the created device group. Can be used to perform a GET request to retrieve the device group. Only present when status is 201.

    DELETE /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/applicationGroups/{appGroupGuid}

    Available Since:
    12.13.0

    Unassign an application group, by GUID, from a device group.

    Request Parameters
    Name Location Description
    appGroupGuid path GUID of the application group to unassign.
    deviceGroupGuid path GUID of the device group to unassign the application group from.
    Response Codes
    Code Condition Data type
    204 Application group unassigned.
      400 Invalid request. For example, invalid field semantics or missing required field.
      404 Application group not found.

      Device group not found.

      GET /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/applications

      Available Since:
      12.13.0

      Get all applications and application groups assigned to device group.

      Sample response body

        
  {
    "applicationAssignments" : [ {
      "application" : {
        "guid" : "aa291d31-3b51-4424-a09c-7b127ee398a8",
        "name":"sampleApplication",
        "description" : "Our sample app.",
        "os": "android",
        "packageId": "com.sample.app.client",
        "sourceName": "In Store",
        "storeName": "Google Play",
        "securedType": "All Android devices",
        "reviewMode": "PUBLIC"
      },
      "disposition" : "OPTIONAL"
    },
    {
      "applicationGroup" : {
        "guid" : "4e9e07fd-f2f9-4eea-94eb-85524dcecb9e",
        "name" : "Business apps",
        "description" : "App group for Internal marketing department"
      },
      "disposition" : "REQUIRED"
    } ]
   }

      Request Parameters
      Name Location Description
      deviceGroupGuid path GUID of the device group to get assigned applications for
      Response Codes
      Code Condition Data type
      200 OK.
      404 Device group not found.
      Response Body
      Media type Data type Description
      application/vnd.blackberry.applicationassignments-v1+json Application assignments (JSON)

      POST /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/applications

      Available Since:
      12.13.0

      Assign one or more applications or application groups, by GUID, to a device group. If the application or application group is already assigned, the disposition and application config will be updated. Only the GUID field of each application, application config or application group is required along with disposition. NOTE: The "DENIED" disposition is not supported for application groups. Application config property is optional. Only application config GUID is required to define an app config. NOTE: Application config cannot be assigned to application group. NOTE: Only BlackBerry Dynamics app configs are supported.

      Sample request body

        
  {
    "applicationAssignments" : [ {
      "application" : {
        "guid" : "aa291d31-3b51-4424-a09c-7b127ee398a8"
      },
      "disposition" : "OPTIONAL"
    }, {
      "application" : {
        "guid" : "841e0146-07d5-4963-947c-dcabe7293806"
      },
      "disposition" : "REQUIRED"
    }, {
      "applicationGroup" : {
        "guid" : "6d0c4ddb-10ae-471d-948d-df27868dcf8a"
      },
      "disposition" : "OPTIONAL"
    } ]
   }

      Sample request body with application config defined

       
 {
     "applicationAssignments": [{
             "application": {
                 "guid": "ef7fb3f4-5ed5-4f53-b54d-c0280cbf2716"
             },
             "disposition": "OPTIONAL",
             "applicationConfig": {
                 "guid": "A2BA5128-FE07-4DF9-AE09-5FC31F4C774E"
             }
         },
         {
             "application": {
                 "guid": "c2cff83f-bbe0-4903-b2e9-557278656fe9"
             },
             "disposition": "OPTIONAL",
             "applicationConfig": {
                 "guid": "0651D265-069D-4B79-94C3-B1326B70E130"
             }
         }
     ]
 }

      Request Parameters
      Name Location Description
      deviceGroupGuid path GUID of the device group to assign applications to.
      Request Body
      Media type Data type
      application/vnd.blackberry.applicationassignments-v1+json Application assignments (JSON)
      Response Codes
      Code Condition Data type
      204 Applications(s) assigned.
        400 Invalid request. For example, invalid field semantics or missing required field.
        404 Application not found.

        Device group not found.

        Application group not found.

        DELETE /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/applications/{appGuid}

        Available Since:
        12.13.0

        Unassign an application, by GUID, from a device group.

        Request Parameters
        Name Location Description
        appGuid path GUID of the application to unassign.
        deviceGroupGuid path GUID of the device group to unassign the application from.
        Response Codes
        Code Condition Data type
        204 Application unassigned.
          400 Invalid request. For example, invalid field semantics or missing required field.
          404 Application not found.

          Device group not found.

          GET /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/groups

          Available Since:
          12.13.0

          Get scoped user groups by a specific device group GUID. If no scoped groups are found, an empty group list is included in the response body.

          Sample request

           GET /SRP00000/api/v1/deviceGroups/b7030076-cfb9-43e6-a88c-355b190c1291/groups

          Sample response body

           
 {
   "groups": [{
       "guid": "953a2988-6d25-4399-b40f-477f44c3a482",
       "name": "Scoped group 1",
       "description": "Group description 1",
       "directoryLinked": false
     },{
       "guid": "25311b56-b8a6-41d1-aa37-2d56ebebe524",
       "name": "Scoped group 2",
       "description": "Group description 2",
       "directoryLinked": false
     }]
 }

          Request Parameters
          Name Location Description
          deviceGroupGuid path
          Response Codes
          Code Condition Data type
          200 OK.
          404 Device group not found.
          Response Body
          Media type Data type Description
          application/vnd.blackberry.groups-v1+json Groups (JSON)

          POST /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/groups

          Available Since:
          12.13.0

          Assign one or more scoped user groups to a device group. If a scoped user group listed in the request is already assigned to device group, it is ignored. If one of the scoped user groups listed in the request can’t be assigned to the device group, the entire batch is not added and an error message is returned.

          Sample request

           POST /SRP00000/api/v1/deviceGroups/b7030076-cfb9-43e6-a88c-355b190c1291/groups

          Sample request body

           
 {
   "groups": [{
       "guid": "953a2988-6d25-4399-b40f-477f44c3a482"
     },{
       "guid": "25311b56-b8a6-41d1-aa37-2d56ebebe524"
   }]
 }

          Request Parameters
          Name Location Description
          deviceGroupGuid path
          Request Body
          Media type Data type
          application/vnd.blackberry.groups-v1+json Groups (JSON)
          Response Codes
          Code Condition Data type
          204 OK.
            400 Invalid request. For example, invalid field semantics or missing required field.
            404 Device group not found.
            409 Invalid request. For example, invalid field semantics or missing required field. Or possible incorrect groups nesting like attempt to add All Users group.
            Response Body
            Media type Data type Description
            application/json Groups (JSON)

            DELETE /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/groups/{groupGuid}

            Available Since:
            12.13.0

            Remove scoped user group from a device group. If a scoped user group listed in the request is not assigned to a device group, it is ignored. If a scoped user group listed in the request can’t be removed, the request is not processed and an error message is returned.

            Sample request

             DELETE /SRP00000/api/v1/deviceGroups/b7030076-cfb9-43e6-a88c-355b190c1291/groups/953a2988-6d25-4399-b40f-477f44c3a482

            Request Parameters
            Name Location Description
            deviceGroupGuid path
            groupGuid path
            Response Codes
            Code Condition Data type
            204 OK.
              400 Invalid request. For example, invalid field semantics or missing required field.
              404 Device group not found.

              GET /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/profiles

              Available Since:
              12.13.0

              Get all profiles assigned to a device group.

              Sample response body

               
  {
    "profiles" : [ {
    "guid" : "3d55abd2-c00e-4f5f-abcf-01c92ac777b1",
    "name" : "Sample Policy",
    "categoryName" : "IT_CONFIG",
    "default" : false
    }, {
    "guid" : "6106fce8-83f5-44b3-8288-e8e4e0966561",
    "name" : "Default Email Profile",
    "categoryName" : "EMAIL",
    "default" : false
    } ]
  }

              Request Parameters
              Name Location Description
              deviceGroupGuid path GUID of the device group to get assigned profiles for
              Response Codes
              Code Condition Data type
              200 OK.
              404 Device group not found.
              Response Body
              Media type Data type Description
              application/vnd.blackberry.profiles-v1+json Profiles (JSON)

              POST /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/profiles

              Available Since:
              12.13.0

              Assign one or more profiles, by GUID, to a device group. Only the GUID field of each profile is required.

              Sample request body

               
  {
    "profiles" : [ {
    "guid" : "3d55abd2-c00e-4f5f-abcf-01c92ac777b1"
    }, {
    "guid" : "6106fce8-83f5-44b3-8288-e8e4e0966561"
    } ]
  }

              Request Parameters
              Name Location Description
              deviceGroupGuid path GUID of the group to assign profiles to.
              Request Body
              Media type Data type
              application/vnd.blackberry.profiles-v1+json Profiles (JSON)
              Response Codes
              Code Condition Data type
              204 Profile(s) assigned.
                400 Invalid request. For example, invalid field semantics or missing required field.
                404 Device group not found.

                PUT /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/profiles

                Available Since:
                12.13.0

                Replace all profiles assigned to a device group. All existing profiles are removed and replaced by the list of profiles (by GUID) provided. Only the GUID field of each profile is required.

                Sample request body

                 
  {
    "profiles" : [ {
    "guid" : "3d55abd2-c00e-4f5f-abcf-01c92ac777b1"
    }, {
    "guid" : "6106fce8-83f5-44b3-8288-e8e4e0966561"
    } ]
  }

                Request Parameters
                Name Location Description
                deviceGroupGuid path GUID of the device group to replace profiles for.
                Request Body
                Media type Data type
                application/vnd.blackberry.profiles-v1+json Profiles (JSON)
                Response Codes
                Code Condition Data type
                204 Profile(s) assigned.
                  400 Invalid request. For example, invalid field semantics or missing required field.
                  404 Device group not found.

                  GET /{tenantGuid}/api/v1/deviceGroups/{deviceGroupGuid}/userDevices

                  Available Since:
                  12.13.0

                  Get the user devices assigned to a device group that are listed as Enrolled.

                  Sample response body

                   
 {
     "userDevices": [
         {
             "links" : [ {
                 "rel" : "user",
                 "href" : "https://server01:18084/SRP00000/api/v1/users/59dc743d-f325-4a6c-97ac-44dcb9ef8a0e"
             } ],
             "guid": "2d2d3a7f-076d-46f9-8c25-56cb8eba2800",
             "checkedOut": false,
             "dynamicsDeviceId": "kzsaj8JeVGtyWU6RY7Zh0jidClQ7BwKg",
             "enrollmentType": [
                 "WORK_SPACE_ONLY_AFW"
             ],
             "language": "en_US",
             "lastContactTime": "2017-01-20T11:01:52.400Z",
             "loggingExpiryDate": "2017-01-18T18:18:43.000Z",
             "loggingStatus": "Expired",
             "device": {
                 "guid": "4659aa7f-0a7d-9f69-258c-2800ebaa2800",
                 "activationDate": "2017-01-16T14:47:03.662Z",
                 "activeSyncId": "K6CKULJTID3SDEAIV0ELHBBTTO",
                 "batteryLevel": 95.0,
                 "compromised": false,
                 "externalStorageFree": 12021.0,
                 "externalStorageSize": 16386.0,
                 "hardwareModel": "Desire",
                 "hardwareName": "bravo",
                 "hardwareVendorCompanyName": "HTC Corporation",
                 "homeCarrier": "Rogers",
                 "iccid": "8938 0012 1050 8728 331",
                 "internalStorageFree": 2112.0,
                 "internalStorageSize": 32768.0,
                 "imei": "990000862471854",
                 "meid": "01234567890123456",
                 "os": "Android 5.0",
                 "osFamilyName": "android",
                 "osVersion": "5.0",
                 "ownership": "PERSONAL",
                 "phoneNumber": "4045551234",
                 "serialNumber": "c08088415436112",
                 "udid": "d88496fdf7115ac9f3ab69966cbaf91d960b95036fa68f66489c8ad78f136b5c",
                 "wifiMacAddress": "62:9a:7e:bc:fe:01",
                 "clientId": "com.rim.mobilefusion.client",
                 "clientVersion": "12.34.0.154893"
             }
         },
         {
             "links" : [ {
                 "rel" : "user",
                 "href" : "https://server01:18084/SRP00000/api/v1/users/59dc743d-f325-4a6c-97ac-44dcb9ef8a0e"
             } ],
             "guid": "6dd3a8e2-3f24-48c6-961a-949794f4b554",
             "checkedOut": false,
             "enrollmentType": [
                 "USER_PRIVACY_AFW"
             ],
             "language": "en_US",
             "lastContactTime": "2017-01-23T10:02:12.340Z",
             "loggingExpiryDate": "2017-12-31T12:00:00.000Z",
             "loggingStatus": "Logging",
             "device": {
                 "guid": "8002ebaa-c258-96f9-d7a0a-0082aa7f4659",
                 "activationDate": "2017-01-16T14:47:03.662Z",
                 "activeSyncId": "Q633AGG6QP3FJF6QBNAA81UHB0",
                 "batteryLevel": 64.0,
                 "compromised": false,
                 "externalStorageFree": 12021.0,
                 "externalStorageSize": 16386.0,
                 "hardwareModel": "Desire",
                 "hardwareName": "bravo",
                 "hardwareVendorCompanyName": "HTC Corporation",
                 "homeCarrier": "Rogers",
                 "currentCarrier": "Rogers",
                 "networkRoaming": false,
                 "iccid": "8938 0012 1050 8728 331",
                 "internalStorageFree": 2112.0,
                 "internalStorageSize": 32768.0,
                 "imei": "351756051523999",
                 "meid": "56789012345678901",
                 "ownership": "CORPORATE",
                 "os": "Android 6.0",
                 "osFamilyName": "android",
                 "osVersion": "6.0",
                 "phoneNumber": "2125557890",
                 "securityPatchLevel": "6.0.1.1345",
                 "serialNumber": "c03618841215084",
                 "udid": "82f2aaa813c5a4bc2748b078ca844bdbd6a8fb8eaaa173a389467646cf04d00c",
                 "wifiMacAddress": "b4:52:7e:62:a5:9a",
                 "clientId": "com.rim.mobilefusion.client",
                 "clientVersion": "12.34.0.154893"
             }
         }
     ]
 }

                  Request Parameters
                  Name Location Description Type
                  deviceGroupGuid path GUID of the device group to get all user devices for  
                  includeTotal query If you want the total number of device group user devices (which may be different from the number of device group user devices returned) set this to true; otherwise set to false. By default the total will not be included in the response. boolean
                  max query The maximum number of user device results to get, between 1 and 1000 inclusive. If not specified, a value of 100 will be used. int
                  offset query The number of matching user devices to exclude from the beginning of the list of user devices in the response; greater than or equal to 0. If not specified, a value of 0 will be used to indicate that no matches should be excluded. Used in order to get "pages" of results. For example, to get the first 50 matching user devices, specify max=50 (and optionally offset=0); and to get the next 50 matching user devices specify max=50 and offset=50, and so on. int
                  Response Codes
                  Code Condition Data type
                  200 OK.
                  404 Device group not found.
                  Response Body
                  Media type Data type Description
                  application/vnd.blackberry.userdevices.baseinfo-v1+json User devices base info (JSON)