Requests

FollowAnalytics API accepts and returns JSON messages over HTTPS. Unless otherwise stated, the common end-point is:

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

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:

Example

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

Response

For sucessful requests, you get a JSON message containing:

{
    "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"
            }
        }
    }
}

{
    "success": false,
    "status": 400,
    "error_message": "The request must contain the user email and password."
}

Data Exports

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

{
    "success": true,
    "result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}

{
    "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:

To generate a CSV file, you would call:

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:

{
    "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)

Response

{
    "success": true,
    "result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing start date"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing end date"
}

User analytics metrics

High-level analytics stats for a given app and period.

Response

{
    "success": true,
    "result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing start date"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing end date"
}

Event analysis

Top events of a given app over the defined period.

In case sd and ed are not provided, the data of last 6 days is returned.

Response

{
    "success": true,
    "result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing start date"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing end date"
}

Event context

Analyze the context of a given event over a selected period.

In case sd and ed are not provided, the data of last 6 days of the previous month are returned.

Response

{
    "success": true,
    "result": "Your report is being generated and will be sent to the email user@followanalytics.com when it is completed"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing start date"
}

{
    "success": false,
    "status": 400,
    "error_message": "Missing end date"
}