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.
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.
Cloud4Wi APIs are developed using the OpenAPI standard.
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.
- 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"
}
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"
}
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
)
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"
}
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
You can find your organization 'cid' in your dashboard in the API section of the Developer page
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:
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.
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.
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.
Customers represent the resource associated with mobile users and contacts acquired via Experiences.
Locations represent the physical places where you deploy Devices
Geofences are the geographical regions where you track events of mobile app users
Devices represent all WiFi Access Points or Beacons managed in the account
Last modified 7mo ago