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

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

CSV Exports

API fair use policy

If your account allows CSV 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)

Some APIs listed in the portal allow a full export in CSV 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.

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: