FollowAnalytics Platform APIs
Any FollowAnalytics platform API works as described in this API overview, which includes the authentication details.
The available APIs are the following:
- Events and sessions: fetch all events or sessions for a given app,
- Automated Exports: monitor and configure your automated data exports,
- Devices and users: List your devices, get the sessions of a given device or user,
- Systems of Records: connect your systems and tools to FollowAnalytics, declare and sync attributes on user profiles,
- Segments: list segments and get the list of devices and associated users for any segment created in the product,
- Campaigns: create and manage your campaigns, send push notifications,
- GDPR: request and delete user data
Requests
FollowAnalytics API accepts and returns JSON messages over HTTPS. Unless otherwise stated, the common end-point is:
https://api.follow-apps.com
All requests should include the Accept: application/json
header.
The body of the requests is a JSON document, containing the required additional paramaters
to perform the request. If the request has a body, please also include the header Content-type: application/json
.
Most of the services require authorization. Authorization is granted via an access token that
you can retrieve with the authentication API. All subsequent requests should contain the header
Authorization: Token YOUR_AUTH_TOKEN
.
Responses
Successful requests will have an HTTP status code 200
. The result will have the following
format:
{
"success": true,
"result": {
...
}
}
On the other hand, in case of error, the status code will not be 200
. If there is a logical
or other problem with the initial request, the status code will be in the range of 400
-499
and a message explaining the problem will be returned. If such an error occurs, you will have
to correct the error before attempting to call the server again.
{
"success": false,
"message": "There has been an error."
}
It is adviced, however, to be prepared to handle other unexpected errors, with the status code
in the range if 500
-599
. The errors can occur for various reasons, such as network
connectivity, server unavailability etc. Due to the nature of these error, a formatted message
cannot be always returned. In most cases, you will be able to repeat the request after a while.
Authentication
POST /api/login
Use this service to obtain an authentication token. This token is required to perform all subsequent requests to the other services of the platform, so you should store it for as long as you want to keep your session open.
Body parameters
Login query requires a JSON object with two mandatory fields:
Property | Type | Description | Default |
---|---|---|---|
string | the user's e-mail | required | |
password | string | the user's password | required |
Example
{
"email": "user@followanalytics.com",
"password": "userpassword"
}
Response
For sucessful requests, you get a JSON message containing:
Property | Type | Description |
---|---|---|
auth_token | string | The user authentification token. Needed for all API calls. |
user | object | An object containing more information around the authenticated user. |
Status: 200 OK
{
"success": true,
"result": {
"auth_token": "s0m3th1ngL1k3CC123-ab123",
"user": {
"id": 42,
"uid": "4422",
"first_name": "Mysterious",
"last_name": "User",
"full_name": "Mysterious User",
"email": "user@followanalytics.com",
"entities": [
{
"id": 24,
"name": "GloriousEntity_1",
"description": "description my entity",
"identifier": "FAENTITY_weWeabc",
"active": true,
"qa_api_key": "7U6m3-eY3O2abc",
"prod_api_key": "HEUzqPVTcZabc",
"data_retention_in_months": 18
},
{
"id": 25,
"name": "GloriousEntity_2",
"description": "description my entity",
"identifier": "FAENTITY_weWeABC",
"active": true,
"qa_api_key": "3U5m4-qT3Odppg",
"prod_api_key": "ABCzqPVTcZgabc",
"data_retention_in_months": 18
}
],
"enable": {
"apps": true,
"campaign_view": true,
"campaign_draft": true,
"campaign_publish": true,
"inapp_library_manage": true,
"transactional_campaigns": true,
"ab_testing": true,
"dynamic_campaigns": true,
"web_inbox": true,
"comments": true,
"downloads": true,
"usage_analytics_view": true,
"usage_analytics_manage": true,
"crashes_view": true,
"crashes_manage": true,
"funnels_view": true,
"funnels_manage": true,
"segments_view": true,
"segments_manage": true,
"sor_manage": true,
"apps_manage": true,
"api_keys_manage": true,
"push_certificates_manage": true,
"gdpr_data_manage": true
},
"admin": true,
"superadmin": false,
"prefered_entity": {
"id": 24,
"name": "GloriousEntity_1"
}
}
}
}
Status: 400-Bad Request" (when, for instance, one of the fields required is missing)
{
"success": false,
"status": 400,
"error_message": "The request must contain the user email and password."
}
Data Exports
API fair use policy
If your account allows data exports, and unless your contract states otherwise, usage of the export on the APIs require you to comply to the following guidelines:
- Once set up in production, your systems should not call the export APIs more than once a day each
- After an optional fetch of all historical data since the SDK was first installed, you are expected to do delta exports when possible (use fields such as
updated_since
orsince_date
to only get the fresh data since your last export)
Data and formats
Some APIs listed in the portal allow a full export in CSV or XLS format. When this is the case, the endpoint of the export is mentioned next to the JSON endpoint. The contents of the file are identical to what you would receive through the JSON format, with the exception that it doesn't paginate: you get the full data in one file. All CSV produced by the API are encoded in UTF-8. When you provide a CSV, it must be encoded in UTF-8. Note that JSON files must be encoded in UTF-8 as per the rfc8259.
The export file can be received by:
- email (parameter
skip_email=false
) - accessing a download URL (
skip_email=true
). For more details see the recurrent automated fetching section above.
Response
Status: 200 OK
{
"success": true,
"result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}
Status: 200 OK
{
"success": true,
"result": {
"callback": "https://api.follow-apps.com/api/exports/download_url?export_token=xyz"
}
}
The default format is XLS. You can specify the format you want to retrieve by appending .csv
or .xls
to the endpoint you are calling. For instance, to get an XLS file, you can call any of the 2 paths below:
GET /segments/FASEGMT_abcd12/devices_export?updated_since=...
GET /segments/FASEGMT_abcd12/devices_export.xls?updated_since=...
To generate a CSV file, you would call:
GET /segments/FASEGMT_abcd12/devices_export.csv?updated_since=...
E-mail exports
Exports are generated on request and this can take up to a few minutes. By default, they are sent to your account e-mail address. In this case, the API will return a code 200
if the request was properly registered.
Recurrent automated fetching
On an API which allows CSV export, as we have seen, it is possible to pass the query string parameter skip_email=true
. For instance, here is the call to export the user IDs currently present in a given segment:
GET /segments/FASEGMT_abcd12/devices_export?fields=current_user_id&skip_email=true
Status: 200 OK
{
"success": true,
"result": {
"callback": "https://api.follow-apps.com/api/exports/download_url?export_token=xyz"
}
}
The callback URL provided in the result is where the file will be available once generated. If you call this callback, you can expect the following HTTP codes:
200
: The file is ready and you receive it,202
: JSON response, the token exists, your request is valid, but the file is not ready yet,400
: JSON response, the token is missing, invalid or the download link has expired.
Export-only endpoints
Some endpoints allow you to fetch data even though there is no public counterpart JSON API.
These endpoints match the export buttons you can find in the product interface: clicking these buttons will generate the export and send the link by e-mail to you. You can also call them in an automated way as described in the recurrent automated fetching section above.
Examples:
Performance figures (downloads, engagement, crashes)
GET /api/performance_export?apps=app_identifiers&sd=start&ed=end
Property | Type | Description | Default |
---|---|---|---|
app_identifiers | string | Comma-separated list of app identifiers to limit the export | required |
sd | timestamp | Start of the period, in seconds since epoch. This has to match midnight in UTC | required |
ed | timestamp | End of the period, in seconds since epoch. This has to match midnight in UTC | required |
Response
Status: 200 OK
{
"success": true,
"result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing start date"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing end date"
}
User analytics metrics
High-level analytics stats for a given app and period.
GET /api/apps/app_identifier/analytics/download_metrics?sd=start&ed=end
Property | Type | Description | Default |
---|---|---|---|
apps | string | Comma-separated list of app identifiers to limit the export | required |
sd | timestamp | Start of the period, in seconds since epoch. This has to match midnight in UTC | required |
ed | timestamp | End of the period, in seconds since epoch. This has to match midnight in UTC | required |
Response
Status: 200 OK
{
"success": true,
"result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing start date"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing end date"
}
Event analysis
Top events of a given app over the defined period.
GET /api/events_export?app=app_identifier&sd=start&ed=end
Property | Type | Description | Default |
---|---|---|---|
app | string | App identifier for which the data will be returned | required |
sd | timestamp | Start of the period, in seconds since epoch. This has to match midnight in UTC | required if ed is provided |
ed | timestamp | End of the period, in seconds since epoch. This has to match midnight in UTC | required if sd is provided |
In case sd
and ed
are not provided, the data of last 6 days is returned.
Response
Status: 200 OK
{
"success": true,
"result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing start date"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing end date"
}
Event context
Analyze the context of a given event over a selected period.
GET /api/event_details_export?app=app_identifier&event_id=event_id&sd=start&ed=end
Property | Type | Description | Default |
---|---|---|---|
app | string | App identifier for which the data will be returned | required |
event_id | integer | Identifier of the event to analyze | required |
sd | timestamp | Start of the period, in seconds since epoch. This has to match midnight in UTC | required if ed is provided |
ed | timestamp | End of the period, in seconds since epoch. This has to match midnight in UTC | required if sd is provided |
In case sd
and ed
are not provided, the data of last 6 days of the previous month are returned.
Response
Status: 200 OK
{
"success": true,
"result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing start date"
}
Status: 404 not found
{
"success": false,
"status": 400,
"error_message": "Missing end date"
}