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
​
​
​
​
​
​
​
​
Demo toolkit - Previous
Testlab WiFi setup
Authentication
Last modified 3mo ago
Export as PDF
Copy link
On this page
Get your API keys
Open APIs reference
Base URL
API Responses
Handling large datasets
FAQ
APIs usage terms and rate limits
Splash
Compass
Resources