App Instances (Devices)

Version date: 19 February 2025

---

To authorize, you need to add the header "Authorization: Bearer ..." (get your API KEY in your personal account on "Personal" tab).

Endpoints

• List Devices

---

List Devices

POST https://core.push.express/api/b/v2/query/app-instances

• Description: Retrieves a list of all devices

No more then 5000 records can be returned

Request

curl --url "https://core.push.express/api/b/v2/query/app-instances"
    --request POST
    --header "Authorization: Bearer ..."
    --data '
{
  "app_ids_include": [
    123,
    234
  ],
  "countries_include": [
    "PT",
    "GB"
  ],
  "languages_include": [],
  "audiences_include": [
    "myaud1_1234",
    "myaud2_1234"
  ],
  "event_include": "install"
}
'

Body params:

• app_ids_include, optional, list of int. List of application IDs to include into filter for app instances. If it is empty you don't filter by application IDs.

• countries_include, optional, list of int. List of countries to include into filter for app instances. Follow iso3166_1_alpha2 standard. If it is empty you don't filter by countries.

• languages_include, optional, list of int. List of languages to include into filter for app instances. Follow bcp47_language_tag standard. If it is empty you don't filter by languages.

• audiences_include, optional, list of string. List of audiences to include into filter for app instances. If it is empty you don't filter by audiences.

• event_include, optional, string. Filters devices which had this event in history. If field is not provided it will be set to install i.e. devices are to be chosen regardless of event happened. If it is empty you don't filter by events in history.

Response:

• 200: List of applications retrieved

{
    "active_count":1,
    "app_instances":[
        {
            "external_id":"",
            "transport_token_masked":"***",
            "language":"en",
            "country":"USA",
            "last_active":"2022-04-27 06:11:46",
            "time_install":"2022-04-27T06:07:41Z",
            "notif_perm_granted":true,
            "platform_name":"12",
            "events":{
                "reg":true,
                "dep":true
            },
            "tags":{
                "ad_id":"",
                "webmaster":"",
                "audiences":"123"
            }
        }
    ]
}

If user does't own any devices yet then response is an empty list with active_count equals 0

• active_count, int. The number of active device instances associated with the user based on the request data.

• app_instances, array. List of devices matching the specified filters, each represented as an object with the following attributes:

  • external_id, string. Unique identifier assigned to the device.

  • transport_token_masked, string. Masked transport token used for secure communication.

  • language, string. Language setting of the device, represented as an ISO 639-1 code (e.g., "en").

  • country, string. Country code of the device, represented as an ISO 3166-1 alpha-3 code (e.g., "USA").

  • last_active, datetime. The last recorded activity timestamp of the device in ISO 8601 format.

  • time_install, datetime. Timestamp indicating when the application was installed on the device, in ISO 8601 format.

  • notif_perm_granted, boolean. – Indicates whether the user has granted notification permissions (true if granted, false otherwise).

  • platform_name, string. Operating system version of the device.

  • events, json. Model that contains information about reg and dep events status.

  • reg,boolean. Flag for reg event status (true if it is reg event, false otherwise).

  • dep, boolean. Flag for dep event status (true if it is dep event, false otherwise).

  • events, json. Model that contains information about reg and dep events status.

  • tags, optional. User-specified string tags, map of strings with string keys. Predefined tag names: ad_id, offer, webmaster

---

Error handling

All HTTP response codes 2xx SHOULD be considered as success. Requested action was executed successfully.

All HTTP response codes above 400 MUST be considered as error. Requested action failed. Retries policy should be hold according to HTTP specification.

Common API errors:

• 400 - request error. Request has invalid data. Check you request (url, headers, payload)

• 401 is returned when provided API token is invalid. Check your authentification data.

• 404 is returned when resource doesn't exist. Check your request data.

• All HTTP response codes 5xx - other errors from proxy servers, load balancers, etc. There may or may not have some explanation in response body. These errors always require retries.

API errors have content-type: application/json header and json response body

Example: {"error": "validation error: ...", "req_id":"<string>"}

Response parameters:

• req_id string is a request ID. It is used by support for problem solving, please, provide it to support if problem emerged.

• error object, describing errors.

Non-API errors like 502, 504, etc., may or may not include a description.