User GuideDeveloper GuideAPI Reference
User Guide
Xtremepush.com

Monitor campaigns & users by pulling data periodically

Learn how to use the API to learn more about campaigns, devices and user profiles

Suggest Edits

There are a range of methods available to you to pull data related to campaigns and users to whom you have sent campaigns. Some common use cases are outlined below.

Check that a campaign is live

The simplest method related to campaigns is the campaign info method. This is commonly used to check that campaign templates are live and to validate content before executing them:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/info/campaign \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "id": "CAMPAIGN_ID"
  }'

You can use it with select options if you only need to check certain params:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/info/campaign \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "id": "CAMPAIGN_ID",
    "select": ["active", "messages", "push_text"]
  }'

This is an example response for an active campaign template with iOS and Android push content:

{
    "success": true,
    "code": 200,
    "model": {
        "active": 0,
        "messages": {
            "1": {
                "push_text": "Hi {{first_name}}, {{amount}} has been debited from your account. Tap here if you did not approve this."
            },
            "2": {
                "push_text": "Hi {{first_name}}, {{amount}} has been debited from your account. Tap here if you did not approve this."
            },
            "3": {
                "push_text": null
            },
            "6": {
                "push_text": null
            },
            "4": [],
            "7": [],
            "8": [],
            "9": [],
            "10": [],
            "11": []
        }
    }
}

Check for errors or information for a specific campaign

If you want to periodically check on delivery of a campaign to individual users you can use the push to device list method.

The example below will return any error messages for notifications that failed to deliver referenced by the Xtremepush device ID:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/list/push-devices \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "condition": [
      ["campaign_id", "=", "CAMPAIGN_ID"],
      ["error", "=" , 1]
    ],
    "select": ["campaign_id", "action_id", "message", "create_time", "device_id", "error_message"],
    "order": ["id DESC", "create_time"],
    "limit": 50, 
    "offset": 0
  }'

The response will show if a message failed to deliver and can help you understand the reason, such as the application being uninstalled on a user's device, which is one of the most common reasons for an individual push to fail. Example response with an application uninstall error below:

{
  "code": 200,
  "success": true,
  "data": [{
    "action_id": 759147,
    "campaign_id": 245624,
    "create_time": 1464355910, 
    "device_id": 459923, 
    "error_message": "Application is Uninstalled"
  }],
}

In the case of profile-based channels (such as email, or SMS) you can use the following request to review individual errors. This does not use the device ID.

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/list/push-devices \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "condition": [
      ["campaign_id", "=", "CAMPAIGN_ID"],
      ["error", "=" , 1]
    ],
    "select": ["campaign_id", "action_id", "message_type_name", "message_params", "create_time", "error", "error_message"],
    "order": ["id DESC", "create_time"],
    "limit": 50, 
    "offset": 0
  }'

This example response shows an active campaign template with email content, where some emails could not be sent due to missing required parameters:

{
  "success": true,
  "code": 200,
  "data": [{
    "action_id": 313049676,
    "campaign_id": 9661067,
    "create_time": 1561385901,
    "error": 1,
    "error_message": "Required values are not set",
    "message_params": {"first_name": "Sam", "ref_number": "1234", "user.email": "[[email protected]](mailto:[email protected])"},
    "message_type_name": "email"
  }, {
    "action_id": 311506802, 
    "campaign_id": 9661067, 
    "create_time": 1561314578, 
    "error": 1, 
    "error_message": "Required values are not set", 
    "message_params": {"user.email": "[[email protected]](mailto:[email protected])"},
    "message_type_name": "email"
  }] 
}

You can get info on delivered messages only by changing the error condition to  ["error", "=" , 0]. Removing the select param would give all info for recent successful messages. If you want data on opened messages then you can use an ["open", "=" , 1] condition to filter for data in opened messages. For example:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/list/push-devices \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "o7Sea-OzAGHtJeJHuD53Obyl8sbMuFTk",
    "condition": [
      ["campaign_id", "=", "53573097"],
      ["open", "=" , 1]
    ],
    "select": ["campaign_id", "message", "create_time", "open_time", "device_id"],
    "order": ["id DESC", "create_time"],
    "limit": 50,
    "offset": 0
  }'

Sample response below:

{
  "success": true,
  "code": 200,
  "data": [{
    "campaign_id": 53573097,
    "device_id": 1914404819,
    "open_time": 1620187760,
    "create_time": 1619887871
  }, {
    "campaign_id": 53573097,
    "device_id": 1914404819,
    "open_time": 1619801909,
    "create_time": 1619801469
  }]
}

The device ID in the above examples is the Xtremepush device ID, but you could also include the user ID in your request ("user_id").

Get information on devices

You can query the device info or list methods to get information on devices, for instance, to check if devices are still addressable for push notifications. To check a specific Xtremepush device ID you can use the device info endpoint with a request such as the following:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/info/device \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "id": 626393090
  }'

This will allow you to get useful information on the device such as: if it is currently addressable for push notifications (active & addressable == 1 ), when the app was last opened on this device (open_time), other available IDs like IDFA or Android Ad ID, device info etc.

Sample response below:

{
  "success": true,
  "code": 200,
  "model": {
    "id": 626393090,
    "project_id": PROJECT_ID,
    "application_id": 4069,
    "profile_id": "11e9c59d08df7bd3b7090a22275e6966",
    "create_time": 1566561386,
    "deactivate_time": null,
    "open_time": 1566577961,
    "token": "60549f4dc442ce5eb101158da3240d1990a1f5fbbd96ce1d957f20e69421f8ed",
    "push_sender_id": null,
    "push_keys": null,
    "active": 1,
    "addressable": 1,
    "subscription": 1,
    "type": "ios",
    "environment": "production",
    "email": null,
    "email_addressable": 0,
    "email_subscription": 1,
    "device_id": "73F81292-7A1F-4EBF-B01E-1783B3D46C21",
    "device_idfv": "73F81292-7A1F-4EBF-B01E-1783B3D46C21",
    "device_idfa": "4BD39DFC-198A-484C-A372-B5CA588FF9F2",
    "device_adid": null,
    "device_type": "iPhone",
    "device_model": "iPhone10,5",
    "device_model_name": "iPhone 8 Plus",
    "device_os": "12.4",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "name": "Maria’s iPhone",
    "timezone": "Europe/Dublin",
    "country": "IE",
    "language": "en",
    "language_app": "",
    "browser": null,
    "browser_type": null,
    "browser_version": null,
    "browser_opt_version": null,
    "browser_os_version": null,
    "browser_os_opt_version": null,
    "carrier_name": "vodafone IE",
    "app_version": "1.0",
    "lib_version": "i-23082019-aib",
    "sw_version": null,
    "external_id": "AN_ID_FROM_YOUR_SYSTEM",
    "ga_id": null,
    "key": "TLhYyU-2Qk6sSo3qfSnVsF02ecoGYely",
    "geo": 0,
    "import": 0
  }
}

If you want to periodically check all devices to maintain data on addressable users then you can use the list devices endpoint with pagination and the fields you need:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/list/device \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "select": ["active", "addressable", "external_id", "id", "open_time", "type"],
    "order": ["id DESC", "create_time"],
    "limit": 50,
    "offset": 0
  }'

Sample response below:

{
  "success": true,
  "code": 200,
  "data": [{
    "id": 2453832008,
    "open_time": 1623233688,
    "active": 1,
    "addressable": 1,
    "type": "android",
    "external_id": null
  }, {
    "id": 2452826033,
    "open_time": 1623134275,
    "active": 1,
    "addressable": 0,
    "type": "web",
    "external_id": null
  }]
}

Get information on user profiles

If you want to periodically check all profiles to maintain data on addressable/subscribed users then you can use the list profile method with pagination and the fields you need. For example, the following call will check for users that are email addressable but are not subscribed for email:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/list/profile \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "select": ["email", "email_addressable", "email_subscription", "user_id"],
    "condition": [
      ["email_subscription", "=", 0], 
      ["email_addressable", "=", 1]],
    "order": ["id ASC", "id"],
    "limit": 50,
    "offset": 0
  }'

Sample response below:

{
  "success": true,
  "code": 200,
  "data": [{
    "user_id": "1235",
    "email": "[email protected]",
    "email_addressable": 1,
    "email_subscription": 0
  }]
}

Updated about 3 years ago