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:

  • Apps: create and manage your apps, API keys and push certificates,
  • Events and sessions: fetch all events or sessions for a given app,
  • 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,
  • Locations: list all locations recorded on the devices for a given app,
  • Labels: list, create and manage all your labels
  • Funnels: list, create, explore your funnels and get quick stats about their completions
  • 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
email string the user's e-mail required
password string the user's password required

Example

{
    "email": "user@followanalytics.com",
    "password": "userpassword"
}

Response

For sucessfull 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": "s0m3th1ngL1k3CCyhj-fe_1ebXnf",
        "user": {
            "id": 42,
            "uid": "4422",
            "first_name": "Mysterious",
            "last_name": "User",
            "full_name": "Mysterious User",
            "email": "user@followanalytics.com",
            "entities": [
                {
                    "id": 24,
                    "name": "GloriousEntity"
                }
             ],
            "enable": {
                "segments": true,
                "admin_alerts": false,
                "coupon_campaign": false,
                "transactional_campaign": true,
                "alerts": true,
                "attribution_analytics": true,
                "analytics": true,
                "conversation": true,
                "crashes": true,
                "funnels": true,
                "reputation": true,
                "competitive_intelligence": true,
                "dashboard": true,
                "share_of_voice": false
            },
            "superadmin": false,
            "prefered_entity": {
                "id": 24,
                "name": "GloriousEntity"
            }
        }
    }
}

Status: 400, Non-existing email or mismatching password

{
    "success": false,
    "status": "bad_request",
    "error_message": "Invalid email or 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 or since_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 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, you can pass the query string parameter skip_email=true. For intance, 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 in where the file will be available once generated. If you call this callback, you can expect the following HTTP codes:

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.

Download figures

Whole history of downloads for all of your apps or some of them.

GET /api/downloads_export?apps=app_identifiers

Property Type Description Default
app_identifiers string Comma-separated list of app identifiers to limit the export required

User analytics metrics

High-level analytics stats for a given app.

GET /api/download_metrics?apps=app_identifier&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 minus one second in UTC required

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
ed timestamp End of the period, in seconds since epoch. This has to match midnight minus one second in UTC required

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
ed timestamp End of the period, in seconds since epoch. This has to match midnight minus one second in UTC required