Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

This section of the documentation shows how to manage your apps, API keys and iOS push certificates.

Apps

List

GET /api/apps

or

GET /api/apps?unwanted=false

This API lists all apps available for the user making the request.

Query parameter

Property Type Description Default
unwanted boolean Defines if the list should include apps removed from sale or other inactive apps false

Response

Status: 200 OK

{
    "success": true,
    "result": {
    "apps": [
        {
            "identifier": "FAAPPLI_1234567",
            "localizations": [
                {
                    "language": "fr",
                    "original_name": "BonjourApp",
                    "name": "BonjourApp",
                    "description": null
                }
            ],
            "store_id": "123455688",
            "package_name": "fr.bonjour.app",
            "fcm_key": null,
            "platform": "iOS App",
            "platform_id": "app-store",
            "is_qa": false,
            "has_usage_data": true,
            "has_pem_file": true,
            "last_sdk_version": "4.1.1",
            "children_app_id": [],
            "parent_app_id": null,
            "downloads": 10234,
            "downloads_last_report_date": 0,
            "mau": 321,
            "crm_syncable": false,
            "has_unwanted_status": false,
            "inbox_days_to_live": null,
            "rate_limit": {
                "message_limit": null,
                "period": null
            },
            "gdpr_emails": ["abc@gmail.com","def@gmail.com"],
            "app_groups": [
                {
                    "identifier": "FAAPPGRP_InJ6aAB",
                    "name": "App group4",
                    "created_at": 1537462793
                }
            ],
            "default_tz": "Europe/Paris",
            "newest_version": "1.0",
            "last_version_status": null,
            "last_update": null,
            "app_icon": null,
            "icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "cv_icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "statuses": [
                {
                    "cdate": 1442389928,
                    "state": "prepareForSubmission",
                    "version_number": "1.0.1.8"
                },
                {
                    "cdate": 1437166560,
                    "state": "live",
                    "version_number": "5.5.10"
                }
            ],
            "current_live_version": "5.5.10",
            "current_version": "5.5.10",
            "primary_category": "SocialNetworking",
            "secondary_category": null
            },
              ...
        ]
    } 
}

View

GET /api/apps/app_identifier

Returns one given app, provided the user requesting it has access to it.

Query parameter

Property Type Description Default
app_identifier string The identifier for the app to view required

Response

Status: 200 OK

{
    "success": true,
    "result": {
    "apps": [
        {
            "identifier": "FAAPPLI_1234567",
            "localizations": [
                {
                    "language": "fr",
                    "original_name": "BonjourApp",
                    "name": "BonjourApp",
                    "description": null
                }
            ],
            "store_id": "123455688",
            "package_name": "fr.bonjour.app",
            "fcm_key": null,
            "platform": "iOS App",
            "platform_id": "app-store",
            "is_qa": false,
            "has_usage_data": true,
            "has_pem_file": true,
            "last_sdk_version": "4.1.1",
            "children_app_id": [],
            "parent_app_id": null,
            "downloads": 10234,
            "downloads_last_report_date": 0,
            "mau": 321,
            "crm_syncable": false,
            "has_unwanted_status": false,
            "inbox_days_to_live": null,
            "rate_limit": {
                "message_limit": null,
                "period": null
            },
            "gdpr_emails": ["abc@gmail.com","def@gmail.com"],
            "app_groups": [
                {
                    "identifier": "FAAPPGRP_InJ6aAB",
                    "name": "App group4",
                    "created_at": 1537462793
                }
            ],
            "default_tz": "Europe/Paris",
            "newest_version": "1.0",
            "last_version_status": null,
            "last_update": null,
            "app_icon": null,
            "icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "cv_icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "statuses": [
                {
                    "cdate": 1442389928,
                    "state": "prepareForSubmission",
                    "version_number": "1.0.1.8"
                },
                {
                    "cdate": 1437166560,
                    "state": "live",
                    "version_number": "5.5.10"
                }
            ],
            "current_live_version": "5.5.10",
            "current_version": "5.5.10",
            "primary_category": "SocialNetworking",
            "secondary_category": null
            }
        ]
    } 
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "App not found"
}

Update

PUT /api/apps/app_identifier

Updates the app matching the identifier, provided that the user has rights to access and edit the app.

Edition of apps automatically fetched from store accounts connected to FollowAnalytics is limited to the parent_identifier and name parameters. The others are automatically managed based on the data fetched from these accounts.

Query parameter

Property Type Description Default
app_identifier string The identifier for the app to edit required

Body parameters

Property Type Description Default
name string Name of the app as it will appear in the app list in FollowAnalytics, and as returned by the APIs -
package_name string Package name of the app. Usually follows a reverse domain name pattern, e.g. com.examplesite.appname -
store_id string Store identifier, which can be identical to the package name, or anything that would identify the app uniquely against a given app store. -
sku string Stock Keeping Unit, can be used to store an additional app identifier -
app_type string Either iOS App, Android App or Web App required
qa boolean Denotes if the app should be identified as a QA or Test app -
parent_identifier string Identifier of another app that would be its parent. This allows 2 levels in the app selector in FollowAnalytics. -
domains array of strings For app_type: 'Web App' this represents the list of app domains. This is ignored for all other app_type. -
default_tz string The default timezone of the app, to use for users for which it is missing. Europe/Paris

Response

Status: 200 OK

{
    "success": true,
    "result": {
    "apps": [
        {
            "identifier": "FAAPPLI_1234567",
            "localizations": [
                {
                    "language": "fr",
                    "original_name": "BonjourApp update",
                    "name": "BonjourApp",
                    "description": null
                }
            ],
            "store_id": "123455688",
            "package_name": "fr.bonjour.app",
            "fcm_key": null,
            "platform": "iOS App",
            "platform_id": "app-store",
            "is_qa": false,
            "has_usage_data": true,
            "has_pem_file": true,
            "last_sdk_version": "4.1.1",
            "children_app_id": [],
            "parent_app_id": null,
            "downloads": 10234,
            "downloads_last_report_date": 0,
            "mau": 321,
            "crm_syncable": false,
            "has_unwanted_status": false,
            "inbox_days_to_live": null,
            "rate_limit": {
                "message_limit": null,
                "period": null
            },
            "gdpr_emails": ["abc@gmail.com","def@gmail.com"],
            "app_groups": [
                {
                    "identifier": "FAAPPGRP_InJ6aAB",
                    "name": "App group4",
                    "created_at": 1537462793
                }
            ],
            "default_tz": "Europe/Paris",
            "newest_version": "1.0",
            "last_version_status": null,
            "last_update": null,
            "app_icon": null,
            "icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "cv_icon": {
                "thumb": "https://abc.com/icon.png",
                "medium": "https://abc.com/icon.png",
                "large": "https://abc.com/icon.png"
            },
            "statuses": [
                {
                    "cdate": 1442389928,
                    "state": "prepareForSubmission",
                    "version_number": "1.0.1.8"
                },
                {
                    "cdate": 1437166560,
                    "state": "live",
                    "version_number": "5.5.10"
                }
            ],
            "current_live_version": "5.5.10",
            "current_version": "5.5.10",
            "primary_category": "SocialNetworking",
            "secondary_category": null
            }  
        ]
    } 
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "App not found"
}

Hide/Unhide

When we hide an application this will not be visible anymore on the platform. In order to get it visible, the application can be unhidden. This can be done from Back-Office.

Create

POST /api/apps

Creates an app. Do not forget to add an API key to it to be able to send mobile data form the SDK. To do so, retrieve the identifier from the app returned by this create call, and use the create method on /api/apps/{app identifier}/api_keys, see below for details.

Body parameters

Property Type Description Default
name string Name of the app as it will appear in the app list in FollowAnalytics, and as returned by the APIs required
package_name string Package name of the app. Usually follows a reverse domain name pattern, e.g. com.examplesite.appname required
store_id string Store identifier, which can be identical to the package name, or anything that would identify the app uniquely against a given app store. -
sku string Stock Keeping Unit, can be used to store an additional app identifier -
app_type string Either iOS App, Android App or Web App required
qa boolean Denotes if the app should be identified as a QA or Test app false
parent_identifier string Identifier of another app that would be its parent. This allows 2 levels in the app selector in FollowAnalytics. -
domains array of strings For app_type: 'Web App' this represents the list of app domains. This is ignored for all other app_type. -
default_tz string The default timezone of the app, to use for users for which it is missing. Europe/Paris

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FAAPPLI_1234567",
        "localizations": [
            {
                "language": "fr",
                "original_name": "BonjourApp",
                "name": "BonjourApp",
                "description": null
            }
        ],
        "store_id": "123455688",
        "package_name": "fr.bonjour.app",
        "platform": "iOS App",
        "platform_id": "app-store",
        "is_qa": false,
        "has_usage_data": true,
        "has_pem_file": true,
        "last_sdk_version": "4.1.1",
        "children_app_id": [],
        "parent_app_id": null,
        "downloads": 10234,
        "downloads_last_report_date": 0,
        "mau": 321,
        "has_unwanted_status": false,
        "newest_version": "5.5.10",
        "last_version_status": "prepareForSubmission",
        "last_update": 1442389928,
        "icon": {
            "thumb": "https://abc.com/icon.png",
            "medium": "https://abc.com/icon.png",
            "large": "https://abc.com/icon.png"
        },
        "cv_icon": {
            "thumb": "https://abc.com/icon.png",
            "medium": "https://abc.com/icon.png",
            "large": "https://abc.com/icon.png"
        },
        "statuses": [
            {
                "cdate": 1442389928,
                "state": "prepareForSubmission",
                "version_number": "1.0.1.8"
            },
            {
                "cdate": 1437166560,
                "state": "live",
                "version_number": "5.5.10"
            },
                ...
        ],
        "current_live_version": "5.5.10",
        "current_version": "5.5.10",
        "primary_category": "SocialNetworking",
        "secondary_category": null,
        "default_tz": "Europe/Paris"
    }
}

Status: 400

{
    "success": false,
    "status": 400,
    "messages": [
        {
             "element": "package_name",
             "severity": "error",
             "message": "Package name abcd has already been taken"
        }
    ],
    "errors": [
        "Package name abcd has already been taken"
    ],
    "error_message": "Package name abcd has already been taken"
}

Status: 400

{
    "success": false,
    "status": 400,
    "messages": [
        {
            "element": "app_type",
            "severity": "error",
            "message": "App type can't be blank"
        }
    ],
    "errors": [
        "App type can't be blank"
    ],
    "error_message": "App type can't be blank"
}

API keys

To allow the FollowAnalytics SDK to send mobile data onto an app, an API key has to be used. Several apps can have the same API key, as long as it's defined on each of them.

List

GET /api/apps/app_identifier/api_keys

This API lists all API keys available for the given app.

Query parameter

Property Type Description Default
app_identifier string The identifier for the app for which to list API keys required

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "api_keys": [
            {
                "identifier": "FAAPIKEY_1234567",
                "api_key": "AB1234567890AA",
                "revoked": false,
                "updated_at": 1496823377,
                "created_at": 1496823377
            }
        ]
    }
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

View

GET /api/apps/app_identifier/api_keys/key_identifier

This API returns the API key matching the identifier provided, for the provided app identifier.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the key is defined required
key_identifier string The identifier for the API key to view required

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FAAPIKEY_1234567",
        "api_key": "Zb1234567890aB",
        "revoked": false,
        "updated_at": 1496823377,
        "created_at": 1496823377
    }
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "API key not found"
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

Update

PUT /api/apps/app_identifier/api_keys/key_identifier

Modifies an API key.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the key is defined required
key_identifier string The identifier for the API key to view required

Body parameters

Property Type Description Default
api_key string* The actual key you'd like to use to send data on this app -
revoked boolean A revoked API key cannot be used anymore -
* at least 8 chars, 1 number, 1 lowercase and 1 uppercase letter

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FAAPIKEY_1234567",
        "api_key": "Ab1234567890aB",
        "revoked": false,
        "updated_at": 1496823377,
        "created_at": 1496823377
    }
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "API key not found"
}

Create

POST /api/apps/app_identifier/api_keys

Creates an API key.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the key is defined required

Body parameters

Property Type Description Default
api_key string* The actual key you'd like to use to send data on this app random key
revoked boolean A revoked API key cannot be used anymore false
* at least 8 chars, 1 number, 1 lowercase and 1 uppercase letter

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FAAPIKEY_1234567",
        "api_key": "Ba1234567890bA",
        "revoked": false,
        "updated_at": 1496823377,
        "created_at": 1496823377
    }
}

Status: 400

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

Push certificates

FollowAnalytics needs a push certificate to be able to send push notifications to iOS apps.

Private keys are encrypted in the database, and decrypted when returned by the APIs.

List

GET /api/apps/app_identifier/push_certificates

This API lists all push certificates available for the given app.

Query parameter

Property Type Description Default
app_identifier string The identifier for the app for which to list certificates required

Response

Status: 200 OK

{
    "success": true,
    "result": {
    "push_certificates": [
        {
            "identifier": "FAABCD_9CA_abC",
            "x509_pem": "-----BEGIN CERTIFICATE-----\n nABCDEF1234............\n——END CERTIFICATE-----\n",
            "revoked": true,
            "not_after": "2018-04-06T14:34:07.000Z",
            "not_before": "2017-03-07T14:34:07.000Z",
            "subject": "Test: com.abc.def.test",
            "pkey_pem": "-----BEGIN RSA PRIVATE KEY-----\nABCDEF1234............\n-----END RSA PRIVATE KEY-----\n",
            "uid": "com.abc.def.test"
        },
        ...
    ]
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

View

GET /api/apps/app_identifier/push_certificates/cert_identifier

This API returns the push certificate matching the identifier provided, for the provided app identifier.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the certificate is defined required
cert_identifier string The identifier for the certificate to view required

Response

Status: 200 OK

{
    "success": true,
    "result": {
            "identifier": "FAABCD_9CA_abC",
            "x509_pem": "-----BEGIN CERTIFICATE-----\n nABCDEF1234............\n——END CERTIFICATE-----\n",
            "revoked": true,
            "not_after": "2018-04-06T14:34:07.000Z",
            "not_before": "2017-03-07T14:34:07.000Z",
            "subject": "Test: com.abc.def.test",
            "pkey_pem": "-----BEGIN RSA PRIVATE KEY-----\nABCDEF1234............\n-----END RSA PRIVATE KEY-----\n",
            "uid": "com.abc.def.test"
    }
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "Certificate not found"
}

Update

PUT /api/apps/app_identifier/push_certificates/cert_identifier

Modifies a push certificate.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the certificate is defined required
cert_identifier string The identifier for the certificate to view required

Body parameters

Property Type Description Default
x509_pem string The pem format of the certificate (see the example API outputs) -
pkey_pem string The pem format of the private key (see the example API outputs) -
revoked boolean A revoked certificate cannot be used anymore -

Response

Status: 200 OK

{
    "success": true,
    "result": {
            "identifier": "FAABCD_9CA_abC",
            "x509_pem": "-----BEGIN CERTIFICATE-----\n nABCDEF1234............\n——END CERTIFICATE-----\n",
            "revoked": true,
            "not_after": "2018-04-06T14:34:07.000Z",
            "not_before": "2017-03-07T14:34:07.000Z",
            "subject": "Test: com.abc.def.test",
            "pkey_pem": "-----BEGIN RSA PRIVATE KEY-----\nABCDEF1234............\n-----END RSA PRIVATE KEY-----\n",
            "uid": "com.abc.def.test"
    }
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "Certificate not found"
}

Create

POST /api/apps/app_identifier/push_certificates

Creates a push certificate on the specified app.

Query parameters

Property Type Description Default
app_identifier string The identifier for the app on which the push certificate is to be added required

Body parameters

Property Type Description Default
x509_pem string The pem format of the certificate (see the example API outputs) required
pkey_pem string The pem format of the private key (see the example API outputs) required
revoked boolean A revoked certificate cannot be used anymore false

Response

Status: 200 OK

{
    "success": true,
    "result": {
            "identifier": "FAABCD_9CA_abC",
            "x509_pem": "-----BEGIN CERTIFICATE-----\n nABCDEF1234............\n——END CERTIFICATE-----\n",
            "revoked": true,
            "not_after": "2018-04-06T14:34:07.000Z",
            "not_before": "2017-03-07T14:34:07.000Z",
            "subject": "Test: com.abc.def.test",
            "pkey_pem": "-----BEGIN RSA PRIVATE KEY-----\nABCDEF1234............\n-----END RSA PRIVATE KEY-----\n",
            "uid": "com.abc.def.test"
    }
}

Status: 200 OK

{
    "success": true,
    "messages": [
        {
            "severity": "warning",
            "message": "Push certificate does not match the app bundle ID."
        }
    ],
    "errors": [
        "Push certificate does not match the app bundle ID."
    ],
    "result": {
        "identifier": "FAABCD_9CA_abC",
        "x509_pem": "-----BEGIN CERTIFICATE-----\n nABCDEF1234............\n——END CERTIFICATE-----\n",
        "revoked": true,
        "not_after": "2018-04-06T14:34:07.000Z",
        "not_before": "2017-03-07T14:34:07.000Z",
        "subject": "Test: com.abc.def.test",
        "pkey_pem": "-----BEGIN RSA PRIVATE KEY-----\nABCDEF1234............\n-----END RSA PRIVATE KEY-----\n",
        "uid": "com.abc.def.test"
    }
}

Status: 400

{
    "success": false,
    "status": 400,
    "messages": [
        {
            "element": "pkey_pem",
            "severity": "error",
            "message": "Pkey pem Error parsing private key: Neither PUB key nor PRIV key: nested asn1 error"
        }
    ],
    "errors": [
        "Pkey pem Error parsing private key: Neither PUB key nor PRIV key: nested asn1 error"
    ],
    "error_message": "Pkey pem Error parsing private key: Neither PUB key nor PRIV key: nested asn1 error"
}

Status: 404 not found

{
    "success": false,
    "status": "not_found",
    "error_message": "App not found"
}