App API

Overview

This API documentation covers registration and deregistration of devices.

URL scheme: https://<customer-id>.push.delivery/push-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST.

REST Endpoints

reg

Subscribe device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Other tags the device might be already subscribed to are not affected by this call.

Table 1. Request Parameter Description
Name Description Example

tagId

The ID(s) of the tag

4

tagSourceId

The source ID(s) of the tag

sport_football_team_fcb_goal

appId

The ID of the app

30

appVersion

Optional: the Version of the app

V1.0.11.3b

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/reg
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.

ureg

Unsubscribe device from tag(s). If no tag id or tag sourceId is provided, all existing tag subscriptions for this device will be removed.

Table 2. Request Parameter Description
Name Description Example

tagId

the ID(s) of the tag(s), if omitted and no tagSourceId(s) provided, all tags will be unregistered

4

tagSourceId

The source ID(s) of the tag(s)

sport_football_team_fcb_goal

appId

The ID of the app

30

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/ureg
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request for complete unregistration (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.

list

List subscribed device tags. Source Id of tags is optional.

Table 3. Request Parameter Description
Name Description Example

appId

The ID of the app

4

platformId

The ID of the platform

30

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Table 4. Response Parameter Description
Name Description Example

id

The ID of the tag

6

name

The name of the tag

Sport

tagOptionalParameters

Parameter map (optional)

{ "auto-subscribe": "true", "visible": "true" }

Example URL
https://<customer-id>.push.delivery/push-api/list
Example POST Request (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: application/json)
[
    {
      "id": <tag-id-number>,
      "sourceId" "<tag-id-string>",
      "name": "<tag-name>",
      "tagOptionalParameters":{
        "<optionalParameterMap-key-1>":"<optionalParameterMap-value-1>",
        "<optionalParameterMap-key-2>":"<optionalParameterMap-value-2>"
        ...
      }
    },
    {
      "id": <tag-id-number>,
      "name": "<tag-name>"
    }
]

tags

List available app tags. Tags are grouped. Tags and groups can both optionally have source IDs for external identification. Groups can have sub groups. Tags that are not in any group will appear in the response in the "default" group.

Table 5. Request Parameter Description
Name Description Example

appId

The ID of the app

30

platformId

The ID of the platform

4

Table 6. Response Parameter Description
Name Description Example

name

The name of the tag group

Sport

tags.id

The ID of the tag

6

tags.name

The name of the tag

Football goals

tags.tagOptionalParameters

Parameter map (optional)

{ "auto-subscribe": "true", "visible": "true" }

Example URL
https://<customer-id>.push.delivery/push-api/tags
Example POST Request (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>
}
Example Response without source ID’s (content type: application/json)
[
    {
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "name": "<tag-name>",
                "tagOptionalParameters":{
                    "<optionalParameterMap-key-1>":"<optionalParameterMap-value-1>",
                    "<optionalParameterMap-key-2>":"<optionalParameterMap-value-2>"
                    ...
                }
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]
Example Response with source ID’s (content type: application/json)
[
    {
        "id" : 0,
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "sourceId": "<tag-source-id-string>",
                "name": "<tag-name>"
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "sourceId": "<group-source-id-string>",
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "sourceId": "<sub-group-source-id-string>",
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]

set

Set the subscriptions of a device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Each call will replace whatever subscriptions for this device existed before.

if no tags are provided, the request will be ignored. To unregister the device please use the '/ureg' endpoint.
Table 7. Request Parameter Description
Name Description Example

tagId

The ID(s) of the tag

4

tagSourceId

The source ID(s) of the tag

sport_football_team_fcb_goal

appId

The ID of the app

30

appVersion

Optional: the Version of the app

V1.0.11.3b

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/set
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.