Skip to content

Quick start

Authentication

To be able to use our REST API you first need to create an "API access token" in the MDM. To do so, go to the "API Access" module in the menu.

Starter Kit

By clicking the "New" button, the following menu appears:

Starter Kit

In this menu, you can select the "scope" of the new token and eventually an expiration date. After clicking "Save", your token will appear in the list.

Once your token is created, you will have to set it in the header of each request to the API, as follows:

Authorization: Bearer VEOYp1qe7Z0NI3Y4fsBO9MO9QYhpvF

Throttling

API calls are rate-limited to prevent abusive usage which could degrade the performance of the service.

The mechanism limits the number of requests per client for a given time window. Beyond that limit, the API returns an HTTP error (429 Too Many Requests) until the counter is reset, at the end of the time window.

All API requests are limited to a maximum of 2000 requests per hour per client, except for the following part:

  • Exports (/api/organizations/<id>/exports/): 6 requests per minute per client

A client is identified as a user, an API Access Token or as its IP address if it is not authenticated.

Here is a sample response from a request that was rate-limited. The number of seconds to wait before new requests can be sent is given in the Retry-After header.

HTTP 429 Too Many Requests
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Retry-After: 3254
Vary: Accept

{
    "errors": {
        "detail": "Request was throttled. Expected available in 3254 seconds."
    }
}

API usage examples

For a complete list of all possible API calls, see Definitions.

Obtaining your organization ID

curl -H "Authorization: Bearer fhL62gUGza2pw0TDZLadSfBvUZj6mx" \
    https://my.famoco.com/api/organizations/
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "My Organization",
        }
    ]
}

Listing your devices

curl -H "Authorization: Bearer fhL62gUGza2pw0TDZLadSfBvUZj6mx" \
    https://my.famoco.com/api/organizations/1/devices/
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
          "id": 1,
          "famoco_id": "(01)03770004396001(21)0581",
          "hardware_details": {
            "imei": [
              "010018800000010",
              "010018810000018"
            ],
            "wifi_mac": "00:16:58:01:00:01",
            "bluetooth_mac": "00:16:58:02:00:01",
            "model": "FX200"
          },
          "state_details": {
            "battery": {
              "plugged": 0,
              "voltage": 4048,
              "level": 3,
              "status": 4
            },
            "ip": "127.0.0.1",
            "geolocation_method": "GPS",
            "last_sync": "2015-10-21T07:28:00.582725Z",
            "latitude": "38.6935973",
            "longitude": "-9.20571150",
            "maintenance_status": "In the field",
            "sync_status": "Synced",
            "os_version": "FX200_v1.0",
            "owner_name": "Alan Smithee",
            "product_model": "FX200",
            "system_applications": [
              {
                "package_name": "com.famoco.launcher",
                "package_version_code": 1
              },
              {
                "package_name": "com.famoco.fms",
                "package_version_code": 2
              },
              {
                "package_name": "com.famoco.settings",
                "package_version_code": 3
              }
            ]
          },
          "device_fields": {
            "com.user.appone": {
              "field": "data"
            }
          },
          "heartbeat": "OK",
          "create_date": "2015-10-21T07:28:00.582725Z",
          "update_date": "2015-10-21T07:28:00.582725Z",
          "settings": {
            "volume": 3,
            "dev_mode": true,
            "nfc": false,
            "bluetooth": true,
            "gps": true,
            "auto_timezone": false,
            "timezone": "Etc/GMT+1",
            "fms_sync_interval": 3600000,
            "screen_timeout": 60000,
            "locale": "en_US",
            "wifi": {
              "enabled": true,
              "security": "WPA/WPA2",
              "ssid": "MySecureNetwork",
              "password": "MyS3cur3Passw0rd",
              "sleep_policy": 2
            },
            "apn": {
              "enabled": true,
              "name": "myapn",
              "apn": "network.com",
              "mcc": "787",
              "mnc": "3737",
              "type": [
                "default",
                "mms"
              ],
              "proxy": "string",
              "port": "8000",
              "user": "user",
              "password": "password",
              "server": "string",
              "mmsc": "string",
              "mmsproxy": "string",
              "mmsport": "8080",
              "authtype": 1,
              "protocol": "IPv4V6",
              "roaming_protocol": "IPv6",
              "bearer": 14
            },
            "data": {
              "enabled": true,
              "roaming": true
            }
          },
          "organization": {
            "id": 1,
            "name": "My Organization"
          },
          "profile": {
            "id": 1,
            "name": "Profile One"
          },
          "subscriber_number": 1,
          "is_archived": false,
          "effective_profile": {
            "id": 1,
            "name": "Profile One"
          },
          "prev_effective_profile": 2,
          "applications": [
            1,
            2,
            3
          ],
          "applications_details": [
            {
              "id": 1,
              "package_name": "com.user.appone",
              "package_version_code": 100,
              "package_version_name": "1.0.0",
              "label": "User Application 1",
              "icon": "/media/1/icon_filename_1.png",
              "size": 1024
            },
            {
              "id": 2,
              "package_name": "com.user.apptwo",
              "package_version_code": 200,
              "package_version_name": "2.0.0",
              "label": "User Application 2",
              "icon": "/media/1/icon_filename_2.png",
              "size": 2048
            },
            {
              "id": 3,
              "package_name": "com.user.famocolayer",
              "package_version_code": 100,
              "package_version_name": "1.0.0",
              "label": "Famoco Layer",
              "icon": "/media/1/icon_filename_FL.png",
              "size": 3072
            }
          ],
          "autolaunch_application": 2,
          "autolaunch_application_details": {
            "id": 1,
            "package_name": "com.user.appone",
            "package_version_code": 100,
            "package_version_name": "1.0.0",
            "label": "User Application 1",
            "icon": "/media/1/icon_filename_1.png",
            "size": 0
          }
        }
    ]
}