Getting started

This guide refers to the most recent version of the APIs. Customers using previous API versions in their integrations can refer to the legacy APIs (V2) documentation.

Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can generate an API key from your dashboard at any time. Go to Manage > Developers on the Cloud4Wi dashboard, make sure that you are in the APIs tab, and create your service under API v3.

Select the "Public app" role if you are generating access data for the WiFi SDK. Otherwise, select the “Organization Manager” role.

Also, select the scopes with the related permission (Read or Write), according to the pieces of information you want API to access. The following information about scopes may help you:

• “Organization” is the largest scope on the platform and contains all other scopes. Use it if you want to provide full access.

• The WiFi SDK requires the Customer Read, Customer Write, and Organization Settings Read scopes to work properly.

You can create multiple API keys and secrets, and you can edit or delete them at any time.

Open APIs reference

Cloud4Wi APIs are developed using the OpenAPI standard.

• Browse and test the endpoint on Swagger here

• Download the OpenAPI definition

Base URL

All URLs referenced in the API documentation will have the following base:

https://explore.cloud4wi.com/

REST APIs are served over HTTPS. To ensure data privacy, Cloud4Wi discourages using unencrypted HTTP requests.

API Responses

All endpoints will respond with an HTTP status code (find more details here):

• 200: Successful request

• 201: The request has been accepted

• 401: Unauthorised, invalid client key or secret

• 403: Forbidden, the service is not authorized to access the resource, or the token is invalid/expired

• 409: Conflict, the request had semantic errors or invalid parameters

• 404: The resource does not exist

• 410: This endpoint has been revoked or removed

• 429: Too many requests, rate limit exceeded

• 500: Uncaught application error

Error responses also include an error message where relevant.

Find below the example of an error message:

{     "message": "Access Denied"
}

Handling large datasets

You can use the 'sId' (scroll id) to retrieve a large number of results from a search request.

You have to execute an initial search request without the 'sId' to initialize the scroll session. The API will return the 'sid' parameter in the response.

As a second step, you have to set the received 'sid' along with the following requests. This response will generate a new 'sid', that you can use to retrieve the next batch of results, and so on. You can repeat this process in a loop until the API will not return any result.

The maximum time interval between 2 requests is 60 seconds; after that interval, the 'sid' expires, and the API will not return any result until you submit a new 'sid'.

First request

Request:

GET customers/organizations/[[CID]]?size=100&hasEmail=true&hasPhone=false&ageVerification=true

Response:

{
    "generated": "2019-11-20T16:56:06Z",
    "totalCount": 216,
    "count": 100,
    "sId": "c5ecaa82e6b01e6dcb8d059ede66b8fe32ca25cfb376129fda99585a91e41253",
    "customers": [
      ...
    ]
}

Following requests

GET customers/organizations/[[CID]]?sId=c5ecaa82e6b01e6dcb8d059ede66b8fe32ca25cfb376129fda99585a91e41253

Response:

{
    "generated": "2019-11-20T16:56:30Z",
    "totalCount": 216,
    "count": 100,
    "sId": "36955899909af957fc8a6f8ba7c14ea6c295ce83581a7850ad89b40afff75a7a",
    "customers": [
      ...
    ]
}

{     "message": "Access Denied"
}

FAQ

Where can I find the 'iss'?

The token used has the JWT format (https://en.wikipedia.org/wiki/JSON_Web_Token).

You can find the iss inside the payload of the JWT after you have decrypted it.

Example of decrypted JWT

header:
{
  "alg": "HS256"
}

payload:
{
  "aud": "service",
  "iss": "srv-11111111-zzzz-yyyy-xxxx-2222222",
  "exp": 1574173580,
  "iat": 1574087186
}

signature:
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret
)

How to check the rate limit?

In each API response, you can find some HTTP headers containing two types of limits.

Requests Rate Limits

Limits are on the number of requests to APIs.

• X-Ratelimit-Limit-Minute: limit per minute

• X-Ratelimit-Remaining-Minute: remaining requests per minute

• X-Ratelimit-Limit-Day: limit per day

• X-Ratelimit-Remaining-Day: remaining requests per day

Objects Rate Limits

Limits are on the number of objects elaborated (created/returned/edited/deleted) through the APIs.

• X-Ratelimit-Limit-<object>-Day: limit per object</object>

• X-Ratelimit-Remaining-<object>-Day: remaining objects per day</object>

Where <object> is the object to which the limit refers</object>

If you reach any of the limits, then the API will return an HTTP/1.1 429 status code to the client with the following JSON body:

{ 
    "message": "API rate limit exceeded" 
}

What is the 'cid'?

The 'cid' a string that univocally identifies an object. It is related to the type of the object of the request, for example in the API

/v1/customers/[[CID]]

the 'cid' is the identifier of the customer object

‍

Where can I find the 'cid' of the organization?

You can find your organization 'cid' in your dashboard in the API section of the Developer page

‍

APIs usage terms and rate limits

The Cloud4Wi public endpoints are powered by the same underlying technology that powers the core Cloud4Wi application. As a result, Cloud4Wi engineering closely monitors the usage of the public APIs to ensure a quality experience for users of the Cloud4Wi applications.

All integrations must comply with the Cloud4Wi Terms of Use and API Terms of Use. Please see these pages for more details:

• Master Subscription Agreement

• API Terms of Use

All versions of APIs are subject to limits:

• burst: 60 requests/minute

• daily: 15.000 requests/day

Moreover, the APIs have rate and volume limits depending on your Cloud4Wi subscription.

Splash

Usage of APIs is subject to our fair usage policy of 2000 Objects/Month per Subscription (per Access Point). Objects include any type of record exchanged via APIs or webhooks, including Users, Logs, Location, and Access Points. API endpoints that retrieve aggregated analytics and metrics count as a single object.

For example, a customer with 100 Splash Subscriptions would be allowed 200,000 objects per month.

The volume of transferred objects will be monitored on a monthly basis. If Clients exceed this allowance in the previous month, they can purchase additional Overage Subscriptions to extend the overall limit of max objects/month. If they do not extend their allowance, a hard threshold on the API volume will be enforced.

On top of the limit above, Cloud4Wi imposes a generic burst rate limit of 60 hits / 60 seconds on all the REST APIs.

Compass

Usage of APIs is subject to our fair usage policy of 10 Objects/Month per Contact. Objects include any type of record exchanged via APIs or webhooks, including Contact Profile, Event Log, Location, and Access Points. API endpoints that retrieve aggregated analytics and metrics count as a single object for each API hit.

The volume of transferred objects will be monitored on a monthly basis. If Clients exceed this allowance in the previous month, they can purchase additional Overage Subscriptions to extend the overall limit of max objects/month. If they do not extend the allowance, a hard threshold on the API volume will be enforced.

On top of the limit above, Cloud4Wi imposes a generic burst rate limit of 60 hits / 60 seconds on all the REST APIs.

Resources

Customers represent the resource associated with mobile users and contacts acquired via Experiences.

Contacts

Locations represent the physical places where you deploy Devices

Locations

Geofences are the geographical regions where you track events of mobile app users

Geofences

Devices represent all WiFi Access Points or Beacons managed in the account

Devices