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

CSV 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 date Date since when the device information has to have been updated to appear in the API output. Allows for delta syncs -

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
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_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
last_seen_at datetime Last time the app was launched on the device
first_seen_at datetime First time the app was launched on 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.
last_country string Last country the device was seen in, based on the device IP
last_isocode string Isocode of the last country the device was seen in, based on the device IP
last_language string Isocode for the last language configured on the device
last_version_number string Last version of the app seen on the device
last_os 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
last_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
attribution_publisher string Name of the attribution publisher through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_campaign string Name of the attribution campaign through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_advertising_identifier string IDFA or Google IFA for the device. Is only available if received through an Attribution partner, see the Attribution section
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
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_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
last_seen_at datetime Last time the app was launched on the device
first_seen_at datetime First time the app was launched on 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.
last_country string Last country the device was seen in, based on the device IP
last_isocode string Isocode of the last country the device was seen in, based on the device IP
last_language string Isocode for the last language configured on the device
last_version_number string Last version of the app seen on the device
last_os 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
last_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
attribution_publisher string Name of the attribution publisher through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_campaign string Name of the attribution campaign through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_advertising_identifier string IDFA or Google IFA for the device. Is only available if received through an Attribution partner, see the Attribution section
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

CSV 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 date Date since when the device information has to have been updated to appear in the API output. Allows for delta syncs -

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
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_out boolean Status of the device regarding push notifications
uninstalled boolean Tells if the app seems uninstalled from the device
last_seen_at datetime Last time the app was launched on the device
first_seen_at datetime First time the app was launched on 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.
last_country string Last country the device was seen in, based on the device IP
last_isocode string Isocode of the last country the device was seen in, based on the device IP
last_language string Isocode for the last language configured on the device
last_version_number string Last version of the app seen on the device
last_os 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
last_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
attribution_publisher string Name of the attribution publisher through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_campaign string Name of the attribution campaign through which this device was acquired. Is only available if received through an Attribution partner, see the Attribution section
attribution_advertising_identifier string IDFA or Google IFA for the device. Is only available if received through an Attribution partner, see the Attribution section
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"
}