endpoint and authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

App devices

Retrieve the devices on which an app is installed.

List

GET /api/apps/app_identifier/devices?page=page&per_page=per_page&fields=fields&current_user_ids=current_user_ids&device_ids=device_ids&segment_ids=segment_ids&updated_since=updated_since

Export endpoint (see how to use it here):

GET /api/apps/app_identifier/devices_export?fields=fields&current_user_ids=current_user_ids&device_ids=device_ids&segment_ids=segment_ids&updated_since=updated_since

Query parameters

Property Type Description Default
app_identifier string The app unique identifier required
page integer The page of devices to retrieve. Negative values will be ignored, and the default number will be used. 1
per_page     integer   The number of device ids to retrieve per page.
Range of values accepted is [1..10000]. Values outside of range are ignored, and the default value is used instead.  		 1000
fields string A string with a list of device fields to present, separated by commas. Example: fields=current_user_id,users. If there's no value for some field requested, the value null is returned for that field.
See table below for possible fields.		 -
current_user_ids string List of comma-separated user_id's to filter the device list by who is logged in on them -
device_ids string List of comma-separated device_id's to filter the device list by some ids -
segment_ids string List of comma-separated segment_id's to filter the device list by a list of segments to search in -
updated_since datetime Date since when the device information has to have been updated to appear in the API output. Allows for delta syncs. Expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -

Response fields

Value Type Description
device_id string Always returned Unique identifier of the device
application_id string Always returned Unique identifier of the application
current_user_id string Identifier of the user connected on the device during the last session recorded
users array of maps Array of users ever seen for this device on this app. The array contains maps with field user_id
users:user_id string Alternate way to request all user_ids for the device on the given app
last_user_id string Last user id logged in for the device on the given app
segments array of maps Array of segments in which the device is for this app. The array contains maps with field segment_id, and optionally name
segments:segment_id string Alternate way to request all segment_ids for the device on the given app
segments:name string Name of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
segments:description string Description of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
opt_in boolean Status of the device regarding push notifications
opt_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
number_of_sessions integer Total number of sessions of the app on the device
number_of_sessions_30d integer Number of sessions of the app on the device over the last 30 days
total_session_duration integer Total time spent in the app on this device
total_session_duration_30d integer Time spent in the app on this device over the last 30 days
last_city string Last city the device was seen in. Requires geolocation to be active in the app.
country_code string Last country the device was seen in, based on the device IP
language_code string Isocode for the last language configured on the device
app_version string Last version of the app seen on the device
os_version string Last OS version seen on the device
sdk_version string Last SDK version seen for the app on the device
device_model string Model of the device
device_type string Type of the device
last_location_latitude float Last latitude obtained through geolocation in the app
last_location_longitude float Last longitude obtained through geolocation in the app
timezone_offset integer Last time zone offset from UTC seen on the device
number_of_crashes integer Total number of crashes of the app of the device
number_of_crashes_30d integer Number of crashes of the app of the device over the last 30 days
first_campaign_received_at datetime First time a campaign targeted this device
last_campaign_received_at datetime Last time a campaign targeted this device
first_opened_app_at datetime Date when then first, valid, session occurred for this device
last_opened_app_at datetime Date when then last, valid, session occurred for this device
updated_at datetime Date the data last changed for this device on this app

Response

Status: 200 OK

{
  "result": {
    "items": [
      {
        "device_id": "713E3BB7-38AA-4D3F-88D1-CE0A1219D7D2",
        "application_id": "FAAPPLI_Fr5tg2e",
        "current_user_id": "carroll@dietrich.info",
        "users": [{
          "user_id": "carroll@dietrich.info"
        }]
      },
      {
        "device_id": "F84EE129-CAE2-44C0-B5AC-7A2F90FE4E16",
        "application_id": "FAAPPLI_Fr5tg2e",
        "current_user_id": null,
        "users": []
      },
      {
        "device_id": "E3BBD7D7-7C99-4F5E-8FC5-A6178946C37D",
        "application_id": "FAAPPLI_Fr5tg2e",
        "current_user_id": null,
        "users": []
      },
      {
        "device_id": "63FF3C41-07D1-4218-A9CE-3063899BC9F5",
        "application_id": "FAAPPLI_Fr5tg2e",
        "current_user_id": "lon.ferry@heidenreich.name",
        "users": [{
          "user_id": "lon.ferry@heidenreich.name"
        },
        {
          "user_id": "robert@jackson.org"
        }]
      }
    ],
    "total_pages": 4,
    "total_items": 20,
    "item_count": 5,
    "navigation": {
      "first": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=1&fields=users,current_user_id",
      "prev": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=1&fields=users,current_user_id",
      "next": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=3&fields=users,current_user_id",
      "last": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=4&fields=users,current_user_id"
    }
  },
  "success": true
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "Couldn't find App"
}

View

GET /api/apps/app_identifier/devices/device_identifier?fields=fields

Retrieve one device using its identifier.

Query parameters

Property Type Description Default
app_identifier string The app unique identifier required
device_identifier string The unique identifier for the device to retrieve. required
fields string A string with a list of device fields to present, separated by commas. Example: fields=current_user_id,users. If there's no value for some field requested, the value null is returned for that field.
See table below for possible fields.		 -

Response fields

Value Type Description
device_id string Always returned Unique identifier of the device
application_id string Always returned Unique identifier of the application
current_user_id string Identifier of the user connected on the device during the last session recorded
users array of maps Array of users ever seen for this device on this app. The array contains maps with field user_id
users:user_id string Alternate way to request all user_ids for the device on the given app
last_user_id string Last user id logged in for the device on the given app
segments array of maps Array of segments in which the device is for this app. The array contains maps with field segment_id, and optionally name
segments:segment_id string Alternate way to request all segment_ids for the device on the given app
segments:name string Name of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
segments:description string Description of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
opt_in boolean Status of the device regarding push notifications
opt_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
number_of_sessions integer Total number of sessions of the app on the device
number_of_sessions_30d integer Number of sessions of the app on the device over the last 30 days
total_session_duration integer Total time spent in the app on this device
total_session_duration_30d integer Time spent in the app on this device over the last 30 days
last_city string Last city the device was seen in. Requires geolocation to be active in the app.
country_code string Last country the device was seen in, based on the device IP
language_code string Isocode for the last language configured on the device
app_version string Last version of the app seen on the device
os_version string Last OS version seen on the device
sdk_version string Last SDK version seen for the app on the device
device_model string Model of the device
device_type string Type of the device
last_location_latitude float Last latitude obtained through geolocation in the app
last_location_longitude float Last longitude obtained through geolocation in the app
timezone_offset integer Last time zone offset from UTC seen on the device
number_of_crashes integer Total number of crashes of the app of the device
number_of_crashes_30d integer Number of crashes of the app of the device over the last 30 days
first_campaign_received_at datetime First time a campaign targeted this device
last_campaign_received_at datetime Last time a campaign targeted this device
first_opened_app_at datetime Date when then first, valid, session occurred for this device
last_opened_app_at datetime Date when then last, valid, session occurred for this device
updated_at datetime Date the data last changed for this device on this app

Response

Status: 200 OK

{
  "result": {
    "device_id": "713E3BB7-38AA-4D3F-88D1-CE0A1219D7D2",
    "application_id": "FAAPPLI_Fr5tg2e",
    "current_user_id": "carroll@dietrich.info",
    "users": [{
      "user_id": "carroll@dietrich.info"
    }]
  },
  "success": true
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "Couldn't find App"
}

Segment devices

GET /api/segments/segment_identifier/devices?page=page&per_page=per_page&fields=fields&current_user_ids=current_user_ids&updated_since=updated_since

Export endpoint (see how to use it here):

GET /api/segments/segment_identifier/devices_export?fields=fields&current_user_ids=current_user_ids&updated_since=updated_since

Query parameters

Property Type Description Default
segment_identifier string The segment unique identifier required
page integer The page of devices to retrieve. Negative values will be ignored, and the default number will be used. 1
per_page     integer   The number of device ids to retrieve per page.
Range of values accepted is [1..10000]. Values outside of range are ignored, and the default value is used instead.  		 1000
fields string A string with a list of device fields to present, separated by commas. Example: fields=current_user_id,users. If there's no value for some field requested, the value null is returned for that field.
See table below for possible fields.		 -
current_user_ids string list of comma-separated user_id's to filter the device list by who is logged in on them -
updated_since datetime Date since when the device information has to have been updated to appear in the API output. Allows for delta syncs. Expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -

Response fields

Value Type Description
device_id string Always returned Unique identifier of the device
application_id string Always returned Unique identifier of the application
current_user_id string Identifier of the user connected on the device during the last session recorded
users array of maps Array of users ever seen for this device on this app. The array contains maps with field user_id
users:user_id string Alternate way to request all user_ids for the device on the given app
last_user_id string Last user id logged in for the device on the given app
segments array of maps Array of segments in which the device is for this app. The array contains maps with field segment_id, and optionally name
segments:segment_id string Alternate way to request all segment_ids for the device on the given app
segments:name string Name of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
segments:description string Description of the segments the device is in. Requesting this field alone will also return the segment_id, which is the default field for this relation
opt_in boolean Status of the device regarding push notifications
opt_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
number_of_sessions integer Total number of sessions of the app on the device
number_of_sessions_30d integer Number of sessions of the app on the device over the last 30 days
total_session_duration integer Total time spent in the app on this device
total_session_duration_30d integer Time spent in the app on this device over the last 30 days
last_city string Last city the device was seen in. Requires geolocation to be active in the app.
country_code string Last country the device was seen in, based on the device IP
language_code string Isocode for the last language configured on the device
app_version string Last version of the app seen on the device
os_version string Last OS version seen on the device
sdk_version string Last SDK version seen for the app on the device
device_model string Model of the device
device_type string Type of the device
last_location_latitude float Last latitude obtained through geolocation in the app
last_location_longitude float Last longitude obtained through geolocation in the app
timezone_offset integer Last time zone offset from UTC seen on the device
number_of_crashes integer Total number of crashes of the app of the device
number_of_crashes_30d integer Number of crashes of the app of the device over the last 30 days
first_campaign_received_at datetime First time a campaign targeted this device
last_campaign_received_at datetime Last time a campaign targeted this device
first_opened_app_at datetime Date when then first, valid, session occurred for this device
last_opened_app_at datetime Date when then last, valid, session occurred for this device
updated_at datetime Date the data last changed for this device on this app

Response

Status: 200 OK

{
  "result": {
    "items": [
      {
        "device_id": "713E3BB7-38AA-4D3F-88D1-CE0A1219D7D2",
        "current_user_id": "carroll@dietrich.info",
        "users": [{
          "user_id": "carroll@dietrich.info"
        }]
      },
      {
        "device_id": "F84EE129-CAE2-44C0-B5AC-7A2F90FE4E16",
        "current_user_id": null,
        "users": []
      },
      {
        "device_id": "E3BBD7D7-7C99-4F5E-8FC5-A6178946C37D",
        "current_user_id": null,
        "users": []
      },
      {
        "device_id": "63FF3C41-07D1-4218-A9CE-3063899BC9F5",
        "current_user_id": "lon.ferry@heidenreich.name",
        "users": [{
          "user_id": "lon.ferry@heidenreich.name"
        },
        {
          "user_id": "robert@jackson.org"
        }]
      }
    ],
    "total_pages": 4,
    "total_items": 20,
    "item_count": 5,
    "navigation": {
      "first": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=1&fields=users,current_user_id",
      "prev": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=1&fields=users,current_user_id",
      "next": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=3&fields=users,current_user_id",
      "last": "http://api.follow-apps.com/segments/segmentIdentifier/devices?page=4&fields=users,current_user_id"
    }
  },
  "success": true
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "Couldn't find Segment"
}