NAV Navbar
cURL python

Introduction

Code Examples with response data. This side panel will give you code examples as to how to use the API. You can switch between the example languages using the tabs above.

Welcome to the Supafi API! You can use our API to access your clients information and usage data.

We have language bindings in Curl and Python, and we can provide example in other languages if required. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

If you have any issues, please contact support@performancenetworks.co.uk.

Authentication

To authorize, use this code:

curl -X GET
     -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
     'https://<APIURL>/users/registrations'

import requests

url = "https://<APIURL>/users/registrations"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

Make sure to replace wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k with your API key.

Authenticate your account when using the API by including your secret API key in the request as a header. You can register for a new Supafi API key by emailing support@performancenetworks.co.uk. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code or plaintext in your code.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

THe API will look for a HTTP header with the key SUPAFI-API-KEY on each request. An invalid or missing API key will result in an HTTP 403 Forbidden.

SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k

IP Whitelists

When setting your account up we will ask you to provide a list of IP addresses that should have access to our API. Our API keys can have different access levels so your IP whitelist should be specified per API key. This gives you granular level control over what services can access what data.

Errors

An example error returned as JSON The startingafter parameter should be a positive integer. This is what would be shown if you passed added the parameter startingafter with a value of dave. 

{
  "status": false,
  "message": "The startingafter variable should be a positive integer"
}

Supafi uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an invlaid attribute or filter was sent etc.), and codes in the 5xx range indicate an error with Supafi's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., there is no data to return), we return a 404 'Not Found' error code.

Error Code Meaning
200 Everything worked as expected
400 Bad Request -- Your request is invalid, often due to a missing parameter
401 Unauthorised - No valid API key provided
403 Forbidden -- The resource requested is hidden for administrators only
404 Not Found -- The specified resource could not be found
405 Method Not Allowed -- You tried to access a resource with an invalid method
406 Not Acceptable -- You requested an invalid format
409 Conflict -- Can happen if the resource you are trying to create already exists. Duplicate email etc.
410 Gone -- The resource requested has been removed from our servers
429 Too Many Requests hit the API! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Content Types

You can retreive your data in various formats. JSON is returned by default, but you can use the "Accept" header to change the format of the returned data.

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   -H "Accept: application/xml"
   'https://<APIURL>/usage'

import requests

url = "https://<APIURL>/usage"
headers = {
    'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k',
    'Accept': 'application/xml'
    }
response = requests.request("GET", url, headers=headers)

print(response.text)

You can see that various allowed types on the left. The above would return the XML below

<?xml version="1.0" encoding="utf-8"?>

<xml>
    <hasmore>1</hasmore>
    <data>
        <datum>
            <usage_id>4401</usage_id>
            <email>matt@silverark.co.uk</email>
            <user_id>1981</user_id>
            <report_date>2015-07-05</report_date>
            <upload>0</upload>
            <download>520</download>
            <full_usage>520</full_usage>
            <new_user>Yes</new_user>
            <locationname/>
            <mac/>
        </datum>
        <datum>
            <usage_id>4402</usage_id>
            <email>testing@supafi.co.uk</email>
            <user_id>29105</user_id>
            <report_date>2015-07-05</report_date>
            <upload>837244</upload>
            <download>1556104</download>
            <full_usage>2393348</full_usage>
            <new_user>No</new_user>
            <locationname/>
            <mac/>
        </datum>

        ...

There are many different formats that you can return your data in. The default format is JSON and we would recommend you stick with that. If needed you can change the format by sending an 'Accept' header in your request.

HTTP Request

curl -X GET -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k" -H "Accept: application/xml" 'https://<APIURL>/usage/startdate/2015-07-05/enddate/2015-07-06'

You can also append the format on to the end of your URL

GET https://<APIURL>/usage.xml

GET https://<APIURL>/usage.array

Formats Available

Format Code Description
array Array data structure
csv Comma separated file
json Default JSON format.
jsonp JSONP format
html HTML using the table library in CodeIgniter
php Using var_export
serialized A serialized php object
xml SImple XML format

Registrations

The below returns the registrations where the registration ID is greater than 13. You could remove startingafter/13 to return rows from the beginning.

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   'https://<APIURL>/registrations/startingafter/13'

import requests

url = "https://<APIURL>/registrations/startingafter/13"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
  "hasmore": false,
  "data": [
    {
      "registration_id": "14",
      "user_id": "173711",
      "source": "website",
      "email": "freedom@silverark.co.uk",
      "registration_date": "2015-08-19 11:01:47",
      "location": "Site 1"
      "location_id": "654654"
    },
    {
      "registration_id": "16",
      "user_id": "173713",
      "source": "website",
      "email": "test@silverark.co.uk",
      "registration_date": "2015-11-17 15:54:56",
      "location": "Site 2"
      "location_id": "1595"
    }
  ]
}

In the above JSON, location may be null if you only have one location. If you have unique identifiers for locations enabled, you will have the set unique id field returned as follows.

{
  "hasmore": false,
  "data": [
    {
      "registration_id": "16",
      "user_id": "173711",
      "source": "website",
      "email": "freedom@silverark.co.uk",
      "registration_date": "2015-08-19 11:01:47",
      "location": "York (City Centre)",
      "location_unique_id": "1234",
    }
  ]
}

If you have custom fields set up in your portal, the custom fields will be included as shown below.

{
  "hasmore": false,
  "data": [
    {
      "registration_id": "16",
      "user_id": "173711",
      "source": "website",
      "email": "freedom@silverark.co.uk",
      "registration_date": "2015-08-19 11:01:47",
      "location": "York (City Centre)",
      "First Name": "Matt",
      "Last Name": "Nelson",
      "Your job": "Developer"
    }
  ]
}

This endpoint retrieves all user registrations on the system. Each registration has an registration_id which increases for each new user on the system, and each new user has a user_id. You can use these ID's to pull information about a specific user, or to filter the registrations list.

HTTP Request

GET https://<APIURL>/registrations

Query Parameters

Parameter Default Description
startingafter (optional) null If set to a registration ID, it will only show the rows after that registration.
limit (optional) 100 The number of rows to return as a positive integer between 1 and 500.

Returns

A dictionary with a data property that contains an array of up to limit registrations, starting after registration startingafter (if set). Each entry in the array is a separate registration object. If no more registrations are available, the resulting data will equal false. This request should never return an error.

Attribute Description
data An array containing the actual response elements, paginated by any request parameters.
hasmore Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Locations

The below returns the Locations where the location ID is greater than 13. You could remove startingafter/13 to return rows from the beginning.

curl -X GET
       -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
       'https://<APIURL>/locations/startingafter/13'
    
import requests

    url = "https://<APIURL>/locations/startingafter/13"
    headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
    response = requests.request("GET", url, headers=headers)

    print(response.text)

The above command returns JSON structured like this:

{
      "hasmore": false,
      "data": [
        {
          "location_id": "3",
          "location_name": "Baker Street",
          },
        {
          "location_id": "4",
          "location_name": "Letsby Ave",
        }
      ]
    }

If you have unique identifiers for locations enabled, you will have the set unique id field returned as follows.

{
      "hasmore": false,
      "data": [
        {
          "location_id": "3",
          "location_name": "Baker Street",
          "location_unique_id": "1212",
          },
        {
          "location_id": "4",
          "location_name": "Letsby Ave",
          "location_unique_id": "1213",
        }
      ]
    }

This endpoint retrieves all locations on the system for your portal. Each location has an location_id which increases for each new location on the system, and each new location has a location_id.

HTTP Request

GET https://<APIURL>/locations

Query Parameters

Parameter Default Description
startingafter (optional) null If set to a location ID, it will only show the rows after that location.
limit (optional) 100 The number of rows to return as a positive integer between 1 and 500.

Returns

A dictionary with a data property that contains an array of up to limit locations, starting after locations startingafter (if set). Each entry in the array is a separate location object. If no more locations are available, the resulting data will equal false. This request should never return an error.

Attribute Description
data An array containing the actual response elements, paginated by any request parameters.
hasmore Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Users

Get all users

The below returns the users in the system attached to your portal. 

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   'https://<APIURL>/users'

import requests

url = "https://<APIURL>/users"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
  "hasmore": false,
  "data": [
    {
      "user_id": "173711",
      "email": "freedom@silverark.co.uk",
      "created_on": "2015-08-19 11:01:47",
      "First Name": "Matt",
      "last Name": "Nelson",
      "Your job": "Elephant Trainer"
    },
    {
      "user_id": "173713",
      "email": "test@silverark.co.uk",
      "created_on": "2015-11-17 15:54:56",
      "First Name": "David",
      "last Name": "Smith",
      "Your job": "Tree Hugger"
    }
  ]
}

This endpoint retrieves all users for your portal. The difference between a user row and a registration row is that only the registration shows the registration source and the location the user registered at.

HTTP Request

GET https://<APIURL>/users

Query Parameters

Parameter Default Description
startingafter (optional) null If set to a user_id, it will only show the users who have an ID greater than that number.
limit (optional) 100 The number of rows to return as a positive integer between 1 and 500.

Returns

A dictionary with a data property that contains an array of up to limit users. Each entry in the array is a separate user object. If no more users are available, the resulting data will equal false. This request should never return an error.

Attribute Description
data An array containing the actual response elements, paginated by any request parameters.
hasmore Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Get a specific User

The below returns a specific User based on their ID.

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   'https://<APIURL>/users/542154'

import requests

url = "https://<APIURL>/users/542154"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
  "user_id": "118978",
  "email": "testingpack@supafi.co.uk",
  "last_login": "2015-04-28 10:37:34",
  "last_auto_login": "0000-00-00 00:00:00",
  "last_ip": "79.77.30.187",
  "created_on": "2015-04-28 10:37:34"
}

This endpoint retrieves a specific user by their user_id.

HTTP Request

GET https://<APIURL>/users/<user_id>

Query Parameters

Parameter Default Description
user_id (required) Required The user_id of the Users

Returns

A dictionary with information about the user.

Usage

Usage data is grouped per user for each location per day. The below returns all the usage rows between 05 July 2015 and 06 July 2015.

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   'https://<APIURL>/usage/startdate/2015-07-05/enddate/2015-07-06'

import requests

url = "https://<APIURL>/usage/startdate/2015-07-05/enddate/2015-07-06"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
  "hasmore": true,
  "data": [
    {
      "usage_id": "4401",
      "email": "test@supafi.co.uk",
      "user_id": "1981",
      "report_date": "2015-07-05",
      "upload": "0",
      "download": "9854",
      "full_usage": "9854",
      "new_user": "Yes",
      "locationname": "Central Library",
      "mac": "AA-BB-CC-DD-EE-FF"
    },
    {
      "usage_id": "4402",
      "email": "testuser@supafi.co.uk",
      "user_id": "29105",
      "report_date": "2015-07-05",
      "upload": "837244",
      "download": "1556104",
      "full_usage": "2393348",
      "new_user": "No",
      "locationname": "Central Library",
      "mac": "AA-BB-CC-DD-EE-FF"
    },

    ...

If hasmore = true then you need to pull the additional pages of data too using the startingafter parameter as shown below and passing in the last usage_id you received in the data.

curl -X GET
   -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"
   'https://<APIURL>/usage/startdate/2015-07-05/enddate/2015-07-06/startingafter/4402'

import requests

url = "https://<APIURL>/usage/startdate/2015-07-05/enddate/2015-07-06/startingafter/4402"
headers = {'supafi-api-key': 'wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'}
response = requests.request("GET", url, headers=headers)

print(response.text)

This endpoint retrieves the usage data for each user on the system. The usage report is group by each user for each location per day. Each grouping has an usage_id which increases as the report is generated each day.

HTTP Request

GET https://<APIURL>/usage

Query Parameters

Parameter Default Description
startingafter (optional) null If set to a usage_id, it will only show the rows after that row.
limit (optional) 100 The number of rows to return as a positive integer between 1 and 500.
startdate (optional) null Including this will only return rows where the report_date is greater or equal to the date. Format: YYYY-MM-DD
enddate (optional) null Including this will only return rows where the report_date is less than or equal to the date. Format: YYYY-MM-DD

Returns

A dictionary with a data property that contains an array of usage rows. If no more usage rows are available, the resulting data will equal false. This request should never return an error.

Attribute Description
data An array containing the actual response elements, paginated by any request parameters.
hasmore Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Mac Whitelist

Get all Whitelisted MACs

The below returns the whitelisted MACs associated with the portal where the whitelist ID is greater than 82. You could remove startingafter/82 to return all rows

curl -X GET
  'https://<APIURL>/whitelist/startingafter/82'
  -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"

import requests

url = "https://<APIURL>/whitelist/startingafter/82"
headers = {'supafi-api-key': "wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
  "hasmore": false,
   "data": [
      {
          "whitelist_id": "83",
          "mac": "FC-CB-32-27-71-7F",
          "created_on": "2018-04-04 14:51:58"
      },
      {
          "whitelist_id": "84",
          "mac": "60-B9-27-44-3B-37",
          "created_on": "2018-04-04 14:51:58"
      }
  ]
}

This endpoint returns all of the whitelisted MACs associated with the portal.

HTTP Request

GET https://<APIURL>/whitelist

Query Parameters

Parameter Default Description
startingafter (optional) null If set to a whitelist ID, it will only show the rows after that whitelisted mac.
limit (optional) 100 The number of rows to return as a positive integer between 1 and 500.

Returns

A dictionary with a data property that contains an array of up to limit whitelisted MACs, starting after the value of startingafter (if set). Each entry in the array is a separate whitelisted MAC object. If no more MACS are available, the resulting data will equal false. This request should never return an error.

Attribute Description
data An array containing the actual response elements, paginated by any request parameters.
hasmore Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Get a specific Whitelisted MAC

The below returns a specific whitelisted mac in the system attached to your portal based on the mac_address. 

curl -X GET
  'https://<APIURL>/whitelist/mac/FC-CB-32-27-71-7F'
  -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"



import requests

url = "https://<APIURL>/whitelist/mac/FC-CB-32-27-71-7F"
headers = {'supafi-api-key': "wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"}
response = requests.request("GET", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
    "whitelist_id": "83",
    "mac": "FC-CB-32-27-71-7F",
    "created_on": "2018-04-04 14:51:58"
}

This endpoint retrieves a specific whitelisted mac by its mac_address

HTTP Request

GET https://<APIURL>/whitelist/mac/<mac_address>

Query Parameters

Parameter Default Description
mac (required) required the mac_address of the whitelisted MAC

Returns

A dictionary with information about the whitelisted MAC. If the requested whitelisted MAC cannot be found, a status of false will be returend with a message.

Add a MAC address to the whitelist

The below adds a MAC address to your portal's whitelist.

curl -X POST
  https://<APIURL>/whitelist
  -H 'supafi-api-key: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k'
  -F mac=11:11:11:11:A1:12

import requests

url = "http://api.supafi.localhost/whitelist"

payload = "{ \"mac\": \"AA-BB-CC-DD-EE-C9\" }"
headers = {
    'SUPAFI-API-KEY': "wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k",
    'Content-Type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

The above command returns JSON structured like this. The ID of the inserted row is returned along with a message:

{
    "mac": "11-11-11-11-A1-12",
    "message": "Added the mac to the whitelist"
}

If the mac address already exists you will receive a 409 status code with the following message

{
    "status": false,
    "message": "Mac address already exists in the white list"
}

If the mac address you have passed through is invalid, you will receive a 400 status code with a message describing what is wrong

{
    "status": false,
    "message": "Invalid length of mac address"
}

This endpoint adds a MAC address to the portal's whitelist.

HTTP Request

POST https://<APIURL>/whitelist

Query Parameters

Parameter Default Description
mac (required) Required The MAC address that is being added to the system (17 chars long in either AA-BB-CC-DD-EE-FF or AA:BB:CC:DD:EE:FF format.)

Returns

The mac_address added along with a message, or a status of FALSE & a message detailing the error such as "Mac address already exists in the white list"

Remove a MAC address from the whitelist

The below removes a specified MAC address from your portal's whitelist based on the mac_address provided. 


curl -X DELETE
  'http://supafiapi.localhost/whitelist/mac/FC-CB-32-27-71-7F'
  -H "SUPAFI-API-KEY: wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"



import requests

url = "https://<APIURL>/whitelist/mac/FC-CB-32-27-71-7F"
headers = {'supafi-api-key': "wgckso8c8scwckg8o4ko084g04k4484wc80g4g4k"}
response = requests.request("DELETE", url, headers=headers)

print(response.text)

The above command returns JSON structured like this:

{
    "mac": "FC-CB-32-27-71-7F",
    "message": "Deleted the mac from the whitelist"
}

This endpoint removes a whitelisted MAC from the whitelist for your portal based on its mac_address

HTTP Request

DELETE https://<APIURL>/whitelist/mac/<mac_address>

Query Parameters

Parameter Default Description
mac required The mac_address of the MAC that is being deleted

Returns

The mac_address of the removed MAC address & a message. Or a status of FALSE with a message as to why the request failed

cURL python