Tag API

Tags are an easy way to group devices. Unlike aliases, of which you can only have one (though a single alias can apply to many devices), many tags can be applied to one or more devices. Then, a message sent to a tag will be sent out to all devices that are associated with that tag.

Tags work on iOS, BlackBerry, and Android (both Helium and C2DM) in the same way, and you can mix and match them together in single push API calls.

Tag Format

Tags can be of any format you wish, but we recommend that they be URL-safe in order to make less work for you. The maximum length of a tag is 128 characters.

Example tags:

• foobar
• some-tag
• a-very-long-but-detailed-tag-hooray
• bar_baz
• 97211
• portland_or

Setting Tags in Device Registration

The primary way to set the list of tags for a device is in registraiton. Each of the platforms can set tag in registration. See the registration section of the relevant platform:

• iOS Device Token Registration
• BlackBerry PIN Registration
• Android APID Registration

Seeing Your Tags

You can see all the tags that you have created with an HTTP GET to /api/tags/. Example response:

{
    "tags": [
        "tag1",
        "some_tag",
        "portland_or"
    ]
}

Adding Tags

There are two methods to create a tag. If you wish to create a tag and not associate any devices with it initially, you can HTTP PUT to /api/tags/<tag> where <tag> is whatever you wish the tag to be (note the lack of a trailing slash; if you do add a trailing slash, it’ll be part of your tag.)

A successful tag creation will return an HTTP status code of 201. If the tag has already been created, it will be 200.

Removing Tags

In order to entirely remove a tag, send an HTTP DELETE to /api/tags/<tag>. The status code on success will be 204.

If the tag has already been removed, the status code will be 404.

Modifying Device Tokens on a Tag

An HTTP POST to /api/tags/<tag> with a content type of application/json and a JSON payload will add or remove device tokens, PINs, or APIDs from that tag. If the tag doesn’t exist, it will be created.

Example:

{
    "device_tokens": {
        "add": [
            "device_token_1_to_add",
            "device_token_2_to_add"
        ],
        "remove": [
            "device_token_to_remove"
        ]
    }
    "device_pins": {
        "add": [
            "device_pin_1_to_add",
            "device_pin_2_to_add"
        ],
        "remove": [
            "device_pin_to_remove"
        ]
    }
    "apids": {
        "add": [
            "apid_1_to_add",
            "apid_2_to_add"
        ],
        "remove": [
            "apid_to_remove"
        ]
    }
}

You must include either a device_tokens, device_pins, or apids section containing an add or remove key (or both) to create the tag. If you wish to create a tag without any device tokens, send an HTTP PUT instead.

Seeing Tags Associated with a Device Token

An HTTP GET to /api/device_tokens/<device_token>/tags/ will show what tags are associated with that device token. It will have a 200 status code unless the device token doesn’t exist; in that case, it will be a 404 (see Registration).

Example response:

{
    "tags": [
        "tag1",
        "some_tag"
    ]
}

Adding a Tag to a Device Token

An HTTP PUT to /api/device_tokens/<device_token>/tags/<tag> will associate the tag with the device token. On success it will return a 201. If that tag has already been associated with that device token, it will return a status code of 200.

Removing Tags from a Device Token

An HTTP DELETE to /api/device_tokens/<device_token>/tags/<tag> will disassociate that device token from that tag. It will not delete the tag entirely. Success will return a 204.

If the tag is not associated with the device token, the return code will be 404.