Devices API | Device Magic Help Center

The devices API allows you to manipulate the devices of your organization.

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 devices API is RESTful, operating on this base URL (note the HTTPS):

https://api.devicemagic.com/organizations/[org_id]/devices

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

Querying your Devices

To retrieve a list of the devices that are part of your organization, send an (authenticated) HTTP GET to:

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

Querying an Individual Device

To retrieve the properties of a particular device in your organization, send an (authenticated) HTTP GET to:

HTTP GET https://api.devicemagic.com/organizations/[org_id]/devices/[device_id].(xml|json)

where the [device_id] is the numeric ID or the identifier field (e.g. 12345, or ‘iPhone_abcdef1234567890’ in the below example) of that device.

Example Response - XML

<device>
    <id>12345</id>
    <identifier>iPhone_abcdef1234567890</identifier>
    <organization-id>10</organization-id>
    <owner>iPhone 4S</owner>
    <description>Scratched, and dropped once or twice</description>
    <pending-approval>false</pending-approval>
    <groups>Default</groups>
    <custom-attributes></custom-attributes>
</device>

Example Response - JSON

{  
    "id":12345,
    "identifier":"iPhone_abcdef1234567890",
    "organization_id":10,
    "owner":"iPhone 4S",
    "description":"Scratched, and dropped once or twice",
    "pending_approval":false,
    "groups":"Default",
    "custom_attributes":{}
}

Approving a Device

You can approve devices for your organization that are pending approval via an authenticated HTTP POST to:

HTTP POST https://api.devicemagic.com/organizations/[org_id]/devices/[device_id]/approve

When you retrieve the XML or JSON for the devices (or a single device) for your organization, there’s an element (containing ‘true’ or ‘false’) that indicates whether a device has been approved.

Approving devices that are already approved has no effect.

Removing a Device from your Organization

Devices can be removed from your organization via an HTTP DELETE to that device’s URL:

HTTP DELETE https://api.devicemagic.com/organizations/[org_id]/devices/[device_id]

Updating the Properties of a Device

An HTTP PUT to the device’s URL will update the properties of the device.

HTTP PUT https://api.devicemagic.com/organizations/[org_id]/devices/[device_id]

The API allows you to update the owner, description, groups, and custom attributes for a device.

The request content of the PUT must be XML or JSON describing the changes you require. You’ll need to set the Content-Type header of the request to application/xml for XML and application/json for JSON.

XML Example

<device>
    <owner>Andy Warhol</owner>
    <description>Eight Elvises</description>
    <groups>Default,Unpublished</groups>
</device>

JSON Example

{  
    "device":{  
        "owner":"Andy Warhol",
        "description":"Eight Elvises",
        "groups":"Default,Unpublished",
        "custom_attributes":{
            "city": "Anchorage",
            "region": "Central"
        }
    }
}

If you leave out any elements in the payload, those properties of the device will be left unchanged.

When you specify groups, provide a comma-separated list of group names. Please don’t include spaces unless they’re actually part of the group name.