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.
For example, 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 is a RESTful API that allows you to search for or create 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.
The v2 API is being introduced to support viewing/filtering groups by labels. Please use the v2 endpoint for any new development request to view groups and continue to use the v1 endpoint for create and delete activities at this time.
Base URL
v2:
https://api.devicemagic.com/api/v2/organizations/[org_id]/groups
v1:
https://api.devicemagic.com/organizations/[org_id]/groups
Substitute your [org_id] above. Your org_id is the numeric value that can be viewed in your URL when you’re logged in and viewing your forms at www.devicemagic.com with your browser.
Viewing Groups
To view all of the groups in an organization you just to do a HTTP GET to the base URL and specify either XML or JSON as response.
HTTP GET https://api.devicemagic.com/api/v2/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.
Query Parameters
Param | Description | Default | Example |
page | The page number to show | 1 | 2 |
Example Response - XML
<groups type="array">
<group>
<id>1</id>
<name>Default</name>
<form_ids type="array">
<form_id>1</form_id>
<form_id>2</form_id>
</form_ids>
<device_ids type="array">
<device_id>1</device_id>
</device_ids>
<tags type="array">
<name>tag1</name>
</tags>
</group>
<group>
<id>2</id>
<name>Unpublished</name>
<form_ids>
<form_id>1</form_id>
</form_ids>
<device_ids>
</device_ids>
<tags type="array">
</tags>
</group>
</groups>
Example Response - JSON
{
"groups": [{
"id": 1,
"name": "Default",
"form_ids": [1, 2],
"device_ids": [1],
"tags": ["tag1"]
}, {
"id": 2,
"name": "Unpublished",
"form_ids": [1],
"device_ids": []
"tags": []
}]
}
Search (filter) for a Group
You can find groups matching a specific substring with the filter option. This replicates searching within the Group UI. Filter is only available for the JSON view.
HTTP GET https://api.devicemagic.com/api/v2/organizations/[org_id]/groups.json?filter=Default
This will return a list of the groups matching the string passed in (e.g. 'Default' as used in this example.)
Example Response
{
"groups": [{
"id": 1,
"name": "Default",
"form_ids": [1, 2],
"device_ids": [1],
"tags": ["tag1"]
}
]
}
Search (filter) by labels (tags)
To retrieve only groups that have a specific label assigned, you can use the following HTTP GET.
HTTP GET https://api.devicemagic.com/api/v2/organizations/[org_id]/groups.json?tags[]=tag1
This will return a list of the groups matching the passed in labels. Multiple tag names can be specified as ...tags[]=tag1&tags[]=tag2&tags[]=tag3 etc. and results will match for any of the tags listed.
Example Response
{
"groups": [{
"id": 1,
"name": "Default",
"form_ids": [1, 2],
"device_ids": [1],
"tags": ["tag1"]
}
]
}
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://api.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://api.devicemagic.com/organizations/[org_id]/groups/[group_id]
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://api.devicemagic.com/organizations/[org_id]/groups/[group_id]
This will remove the group and return a 200 OK.