Advice and answers from the Device Magic Team

The groups API allows you to manage groups within your organization.

Each form is assigned to a group, and devices are members of (potentially multiple) groups. This means you can have certain forms only visible to certain devices.

(You may only want your “New Lead” form visible to your sales team, and while you’re testing new form designs, you may only want those forms visible on test devices.)

This API allows you to create new groups.

If you’re looking to manage the group a form belongs to, please see the forms API.

If you’re looking to organize a device’s groups, please see the devices API.

The API requires you to authenticate each call with your API token. Please see our authentication topic if you need to know more.

Base URL

The groups API is RESTful, operating on this base URL (note the HTTPS):

https://www.devicemagic.com/organizations/[org_id]/groups

where your [org_id] is the same ID in the URL when you’re logged in and viewing your forms at www.devicemagic.com with your browser.

Viewing Groups

To view the groups on an organization you just to do a HTTP GET to the base URL.

HTTP GET https://www.devicemagic.com/organizations/[org_id]/groups.(xml|json)

This will return a list of the groups with the group's name its form ids and device ids.

Example Response - XML

<groups>
  <group>
    <id>1</id>
    <name>Default</name>
    <form_ids>
      <form_id>1</form_id>
      <form_id>2</form_id>
    </form_ids>
    <device_ids>
      <device_id>1</device_id>
    </device_ids>
  </group>
  <group>
    <id>2</id>
    <name>Unpublished</name>
    <form_ids>
      <form_id>1</form_id>
    </form_ids>
    <device_ids>
    </device_ids>
  </group>
  <group>
    <id>9</id>
    <name>Test Group 1</name>
    <form_ids>
    </form_ids>
    <device_ids>      
    </device_ids>
  </group>
</groups>

Example Response - JSON

{
"groups": [{
"id": 1,
"name": "Default",
"form_ids": [1, 2],
"device_ids": [1]
}, {
"id": 2,
"name": "Unpublished",
"form_ids": [1],
"device_ids": []
}, {
"id": 9,
"name": "Test Group 1",
"form_ids": [],
"device_ids": []
}]
}

Creating Groups

To create a group, you’ll need to do an HTTP POST with the names of the groups you’d like to create to

HTTP POST https://www.devicemagic.com/organizations/[org_id]/groups

Creating Groups via XML

If you’d like to create groups via XML, you’ll need to set the content-type header:

Content-Type: application/xml

and your POST body will need to look like this:

<groups>
    <group>
        <name>My New Group Name</name>
    </group>
</groups>

You can specify multiple groups to create at the same time:

<groups>
    <group>
        <name>A First Group</name>
    </group>
    <group>
        <name>A Second Group</name>
    </group>
</groups>

Creating Groups via JSON

If you prefer to use JSON, you’ll need to set the content-type header:

Content-Type: application/json

and your POST body will need to look something like this:

[ "My New Group Name" ]

You can create multiple groups at the same time by providing additional names in your array:

[ "A First Group", "A Second Group" ]

Updating Groups

To update a group, you’ll need to do an HTTP PUT to the ID of the group you would like to update.

HTTP PUT https://www.devicemagic.com/organizations/[org_id]/groups/[group_id].(xml|json)

You can update the name, form_ids and device_ids.

If you do not want to update an attribute, just leave it out.

Updating Groups via XML

If you’d like to update a group via XML, you’ll need to set the content-type header or send the the request to .xml:

Content-Type: application/xml

and your PUT body will need to look like this:

<group>
  <name>An updated group name</name>
  <form_ids>
    <form_id>1</form_id>
    <form_id>2</form_id>
  </form_ids>
  <device_ids>
    <device_id>4</device_id>
    <device_id>5</device_id>
    <device_id>12</device_id>
  </device_ids>
</group>

You can leave out attributes to leave them unchanged:

<group>
  <name>An updated group name</name>
</group>

Updating Groups via JSON

If you prefer to use JSON, you’ll need to set the content-type header or send the request to .json:

Content-Type: application/json

and your PUT body will need to look something like this:

{
  "group": {
    "name": "An updated group name",
    "form_ids": [1,2],
    "device_ids": [4,5,12]
  }
}

You can leave out attributes to leave them unchanged:

{
  "group": {
    "name": "An updated group name"
  }
}

Server Responses for Group Update

If your group was updated, the server will respond with a 200 OK.

If there was an error while updating, the server will respond with a 400 Bad Request and an error message in the body.

Deleting Groups

To delete a group, you’ll need to do an HTTP DELETE to the ID of the group you would like to remove.

HTTP DELETE https://www.devicemagic.com/organizations/[org_id]/groups/[group_id]

This will remove the group and return a 200 OK.

Did this answer your question?