Overview

Welcome to SmartCap's API documentation.

The SmartCap APIs enable you to retrieve data from LifeHub. There are three APIs documented on this site: the Authenticator API, the Data API, and the Reporting API.


Getting Started

Before you can use SmartCap's APIs you will need the following:

Upon recieving your credentials, you will need to reset your client secret and store your newly generated secret for future use. Once you have done this, you will be able to login via the Authenticator API which will allow you to retrieve an authentication token that can be used to access SmartCap APIs.


Usage Plans

Each SmartCap API key is assigned a usage plan which defines usage limits for the key. They are as follows:

1. Standard:

2. Gold:

3. Platinum:

If a request is made with a key which has exceeded these limits, an HTTP response with the status "429 Too Many Requests Exception" will be returned.

For any enquiries regarding your API usage plan, please contact


Additional Information

Diagram of Typical API Flow:

Example API Flow

Example API Code (Python 3):

import requests
import json
from datetime import datetime, timedelta
import logging

logging.basicConfig(level=logging.DEBUG)

API_URL = 'https://api.smartcaplife.com/'


"""
Change the following to match your details. The SITE_NAME is the first part of your LifeHub domain name. e.g. the 
below is for mysite.smartcaplife.com. You will also want to update the functions below to use the desired API versions.
This code is using /v1/ of each API. 
"""
API_KEY = 'owAl9sG7gbZgJ3kzZWIeVhnRWWyp6DJQ'
API_SECRET = 'kTqFpWaWyxWY'
SITE_NAME = "mysite"


def authorize(api_key, api_secret):
    """
    Authorise to get a token to use the SmartCap data API. Use the IdToken property of the returned dict

    :param api_key: API key provided by smartcap (typically 32 chars)
    :param api_secret: API secret/password (typically 12 chars)
    :return: a dict with three keys:
            IdToken: token to be used in subsequent API requests (valid for 30 mins)
            refreshToken: refresh token, used with the /auth/refresh endpoint to get a new IdToken (valid for 5 days)
            tokenType: always bearer
    """
    try:
        # uses HTTP Basic Authentication
        response = requests.post(API_URL + 'v1/auth', auth=(api_key, api_secret))
        response.raise_for_status()

        print(json.dumps(response.json(), indent=4))

        return response.json()

    except requests.RequestException as e:
        if e.response.status_code == 401:
            print('Authentication error - check your API key and secret')

        raise


def refresh_auth(api_key, refresh_token):
    """
    Retrieve a new API token

    :param api_key: API key provided by SmartCap
    :param refresh_token: returned as 'refreshToken' from the call to /auth or /auth/refresh
    :return: a dict with three keys:
            IdToken: token to be used in subsequent API requests (valid for 30 mins)
            refreshToken: refresh token, used with the /auth/refresh endpoint to get a new IdToken (valid for 5 days)
            tokenType: always bearer
    """
    payload = {
        "refreshToken": refresh_token
    }

    headers = {
        "x-api-key": api_key,
    }

    # Note that setting json=payload will automatically add Content-Type: application/json
    # If you set the body a different way, you will need to ensure this header is added
    response = requests.post(API_URL + 'v1/auth/refresh', headers=headers, json=payload)
    response.raise_for_status()

    print(json.dumps(response.json(), indent=4))

    return response.json()


def get_fatigue_logs(api_key, id_token, hours=24):
    """
    Request fatigue log data - default to last 24 hours
    :param api_key: API key provided by SmartCap
    :param id_token: IdToken from authorisation
    :param hours: number of hours to query
    :return: fatigue log response as json
    """
    try:
        payload = {
            "options": {
                "sites": [SITE_NAME],   # must be an array
                "filter": {
                    "from_timestamp": (datetime.utcnow() - timedelta(hours=hours)).strftime('%Y-%m-%d %H:%M'),
                    "to_timestamp": datetime.utcnow().strftime('%Y-%m-%d %H:%M')
                }
            }
        }

        headers = {
            "x-api-key": api_key,
            "Authorization": "Bearer {}".format(id_token)
        }

        # Note that setting json=payload will automatically add Content-Type: application/json
        # If you set the body a different way, you will need to ensure this header is added
        response = requests.post(API_URL + 'v1/data/fatigue', headers=headers, json=payload)
        response.raise_for_status()

        print(json.dumps(response.json(), indent=4))

        return response.json()
    except requests.RequestException as e:
        if e.response.status_code == 400:
            print('Check your request payload and ensure that valid json has been posted')
        if e.response.status_code == 403:
            print('Token Refresh required ')

        raise


if __name__ == "__main__":
    auth = authorize(API_KEY, API_SECRET)

    data = get_fatigue_logs(API_KEY, auth["IdToken"])

    print('Got {} fatigue records'.format(len(data)))

    # at some point - either refresh or authorize again
    auth = refresh_auth(API_KEY, auth["refreshToken"])

    data = get_fatigue_logs(API_KEY, auth["IdToken"], hours=48)

    print('Got {} fatigue records'.format(len(data)))

Code Generation:

SmartCap's documentation makes use of the OpenAPI Specification. When you view our API documentation, you are able to download the specification file that was used to generate it. There are a variety of tools which can make use of this specification file. One that you may be interested in is a Client SDK Generator which is capable of generating boilerplate code for API requests. There's a wide range of different programs which offer this, however, the most reliable is probably the implementation maintained by Swagger.

Generate a Client SDK with Swagger: