Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Browse and test the endpoint on Swagger here
Download the OpenAPI definition
All URLs referenced in the API documentation will have the following base:
REST APIs are served over HTTPS. To ensure data privacy, Cloud4Wi discourages using unencrypted HTTP requests.
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:
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:
Response:
Following requests
Response:
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
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:
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
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
Geofences are the physical regions where the Location SDK tracks entry/eist moments. You can create/import Geofences via the dashboard or using the APIs.
Coming soon.
Using your clientKey and clientSecret you can request for a token by calling the dedicated method (note: replace asterisks with your clientKey and clinetSecret)
If the client key and secret are correct, then the API will return a JWT token.
The JWT token expires after one day; to get a new one, restart and call again /v1/sts/login/services.
Use your client key and client secret to retrieve a valid authentication token
You can manually revoke a token using the following end-point:
Locations represent the physical places where you deploy Devices.
To use the Create Location API the following parameters are mandatory:
locationProfileId
welcomePortalId
loginProfileId
These parameters can be extracted in the following ways:
locationProfileId
In Cloud4Wi dashboard follow the path:
Manage -> Location Profiles -> *Select the Location Profile of interest
welcomePortalId
In Cloud4Wi dashboard follow the path
Guest WiFi -> Splash Pages -> *Select the Splash Page of interest
loginProfileId
In Cloud4Wi dashboard follow the path
Guest WiFi -> Login Profiles -> *Select the Login Profile of interest
In Cloud4wi dashboard follow the path
Guest Wifi -> Internet Plans -> *Select the Internet Plan of interest
Devices include all pieces of HW deployed in your Locations.
To create a new Hotspot using the POST /v3/hotspots endpoint, you need to specify the MAC address of the access point and for some vendors also the Identifier.
The following table specifies for which vendor you need to provide the Identifier attribute. For these vendors, even if the Identifier is the same as the MAC address, it needs to be provided.
Contacts represent the resource associated with mobile users or contacts acquired via Experiences.
Contact object: example
The Contact object may differ depending on the specific API. You can explore the Contact object in the definition of each API endpoint.
Example of Contact object returned by the endpoint https://explore.cloud4wi.com//v2/customers/organizations/{cid}
Segments are dynamic gorup of Contacts matching filtering rules. You can create, edit and delete segments on the dashboard.
WiFi Connections represent every single instance a Contact connect to a WiFi service, either via captive portal, WiFi SDK, WPA2 Enterprise or Passpoint.
The Events endpoint allows you to retrieve all the Contact's location events and application events from your Cloud4Wi account.
List of Events:
"signup": a Contact is created in your Cloud4Wi account, either when a person signs up from the guest WiFi, a Kiosk or via APIs
"visit": a Contact leaves a location after a visit. The event includes the visit metadata such as location and durations
"login": a Contact authenticates to a WiFi network, either on the guest WiFi, WPA2-Enterprise or Passpoint
Vendor | Identifier |
---|---|
The following API allows listing all existing segments. You can use the Segment ID to filter Contacts retrieved with the .
"promo": a Contact clicks on a call to action in the Promo Page interstitial content. See .
"survey": a Contact responds to a survey. See
"send_email": an email has been sent via
"open_email": an email sent via has been opened
"click_email": a of an email sent via has been clicked
"send_sms": an SMS has been sent via
"click_sms": a of an SMS sent via has been clicked
Example of the response of the endpoint
Aerohive Networks, Inc.
Aruba Networks
Required
Cambium Networks Limited
chillispot
Required
Cisco Systems
coovachilli
Required
Cradlepoint
dd-wrt
Required
endian
Required
Endian s.r.l.
Required
EnGenius
EnGenius CP ready
Extreme Networks
FortiNet
Hewlett Packard
Required
Huawei
ICC
Icomera Moovbox
Required
IgniteNet
LigoWave VAC
Meraki
Mojo Networks
Nomadix
Required
Open Mesh
Required
PowerCloud Systems
Required
Routerboard.com
Required
routeros
Required
Ruckus Wireless (Controller)
Ruckus Wireless (SCG)
Required
Ruckus Wireless (Standalone)
Required
Ruckus Wireless (Xclaim)
Required
Samsung
tanaza
tanaza_os
Teldat
Teltonika
Tiesse SpA
Ubiquiti Networks
Wilibox Deliberant Group LLC
Required
Wi-Next s.r.l.
Required
Xirrus Inc
Zebra Technologies Inc
Browan Communication Inc.
Required
It revokes the JWT token passed in the header.
The token has been revoked
Retrieve Contact profile by Id Role: Organization Manager Scope: organization_read, customer_read
id of the customer
Data present
Retrieve list of visits and WiFi connections including metadata such as date and duration. Role: Organization Manager Scope: organization_read, customer_read
id of the customer
Data present
Retrieve device information like WiFi MAC address, number of WiFi connections and last WiFi connection date on the device. Role: Organization Manager Scope: organization_read, customer_read
id of the customer
Data present
Delete an hotspot Role: Organization Manager Scope: hotspots_write, organization_write
Hotspot id
Response
Delete a location Role: Organization Manager Scope: organization_write
id of the organization (aka tenant)
id of the location
Response
Returns a JWT token inside the body and in the Authorization Header of the response
User authenticated
JWT token
Delete a Contact by Id Role: Organization Manager Scope: organization_write, customer_write
id of the customer
Deleted done.
OK
date time of response
Get Access Point by Id Role: Organization Manager Scope: organization_read, hotspots_read
Hotspot id
Hotspot
OK
date time of response
Hotspot id
Hotspot name
date creation. Format iso8601
Hotspot mac address
Retrieve WiFi connections of a specific Contact Id, including metadata such as duration, traffic, access point used Role: Organization Manager Scope: organization_read, customer_read
id of the customer
Array with the accountings
Update an hotspot.
Note:
The properties venueId, routerType, macAddress, hotspotIdentifier, and ssid are not allowed.
Role: Organization Manager
Scope: hotspots_write, organization_write
Hotspot id
country code as ISO 3166-1 alpha-2. Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Response
Update a location Role: Organization Manager Scope: organization_write
id of the organization (aka tenant)
id of the location
desc
valid category: other, consumer electronics, sports center, fast food, disco, pools, bar, ice cream, piano bar, underwear, cinema, computers, footwear, gyms, sandwich, sporting goods, hairstyle, public administration, phone, hotels, pizzeria, coffee, restaurants, clothing, pub
country code as ISO 3166-1 alpha-2.
Response
new tags added
Retrieve all WiFi connection of the organization Role: Organization Manager Scope: organization_read, customer_read
id of the organization (aka tenant)
The sid can be used to retrieve a large number of results from a search request. Read here to get more information about how to use the sid
Number of WiFi Connections returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
Return WiFi Connections occurred on a specific Location Id
Return WiFi Connections occurred on a specific Access Point Id
Return WiFi Connections with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z' or '2019-07-31' but is necessary set timezone
Return WiFi Connections with creation date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z' or '2019-07-31' but is necessary set timezone
Timezone
Array with the list of WiFi Connections
Create a new hotspot
Note:
Depending on the routerType, the fields macAddress, hotspotIdentifier, and ssid may be required, optional, or not allowed. Please refer to the documentation for further information.
Role: Organization Manager
Scope: hotspots_write, organization_write
use according with routerType
use according with routerType
Use address, city, country, zip and state from location
country code as ISO 3166-1 alpha-2. Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Required if addressAsLocation is false
Response
List the segments of an organization Role: Organization Manager Scope: organization_read, segments_read
id of the organization (aka tenant)
Array with the segments
segment id
segment name
segment description
last calculation of segment (date format iso8601)
segment creation date time (date format iso8601)
segmente last modified date time (date format iso8601)
segment status
audience of segment
Get an Access Point by hotspot identifier Role: Organization Manager Scope: organization_read, hotspots_read
Hotspot identifier as configured in the dashboard
Hotspot
OK
date time of response
Hotspot id
Hotspot name
date creation. Format iso8601
Hotspot mac address
For the custom opt-ins add the prefix "customs." to the policyKey. For example, if the custom opt-in has title "emailMarketing" to update it use the policyKey "customs.emailMarketing" Role: Organization Manager Scope: organization_write, customer_write
id of the customer
desc
policy name
true/false
Update done.
the new value of the policyKey
Add a new location Read https://create.cloud4wi.com/dev-hub/api-reference/getting-started/locations for details Role: Organization Manager Scope: organization_write
id of the organization (aka tenant)
desc
In format "Europe/Rome"
country code as ISO 3166-1 alpha-2.
valid category: other, consumer electronics, sports center, fast food, disco, pools, bar, ice cream, piano bar, underwear, cinema, computers, footwear, gyms, sandwich, sporting goods, hairstyle, public administration, phone, hotels, pizzeria, coffee, restaurants, clothing, pub
internet plan id at organization level
Response
new tags added
List hotspots for the organization Role: Organization Manager Scope: organization_read, hotspots_read
id of the organization (aka tenant)
Filter hotspots with date bigger than. Format YYYY-MM-DD
Filter hotspots with date lower than. Format YYYY-MM-DD
Filter by name
Filter by hotspot macaddress
Filter by hotspot identifier
Filter by venueId
Filter by deleted properties. Default deleted=false
Array with the hotspots
OK
date time of response
Hotspot id
Hotspot name
date creation. Format iso8601
Hotspot mac address
Retrieve all Locations configured in the organization Role: Location Manager, Organization Manager Scope: organization_read
id of the organization (aka tenant)
Filter by a tag or a list of tags comma separated
Array with the list of Locations
location id
location name
organization id
latitude
longitude
location's time zone
address
city
state/province/region
zip/postal code
country
List locations belongs to an organization Scope: organization_read
Location id
Array with the list of Locations
location id
location name
organization id
latitude
longitude
location's time zone
address
city
state/province/region
zip/postal code
country
List all events, including WiFi Connections, Visits and applicaiton events of a given Contact Id Role: Organization Manager Scope: organization_read, events_read
id of the organization (aka tenant)
id of the user (ID of the table w.USERS) passed inside the JWT received at login
Return events with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return events with date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
List of events (comma separated). Possible values: visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo
Number of events returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
Sort list by: businessTime, utcTime (default is businessTime)
Reverse sort order
Response
OK
date time of response
visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo
Available if type is visit
Available if type is signup
Available if type is *_email
Available if type is *_sms
Available if type is survey
Available if type is promo
List all Events, including Visits, WiFi connections and application events, of an Organization Retrieve all events og of the given organization . Role: Organization Manager Scope: organization_read, events_read
id of the organization (aka tenant)
Return events with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return events with date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
List of events (comma separated). Possible values: visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo
Number of events returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
Sort list by: businessTime, utcTime (default is businessTime)
Reverse sort order
Enable scroll. If true, the response will contain a scrollId. Use it to get the next page of results.
Scroll id. Use it to get the next page of results.
Response
OK
date time of response
visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo
Available if type is visit
Available if type is signup
Available if type is *_email
Available if type is *_sms
Available if type is survey
Available if type is promo
Role: Organization Manager Scope: organization_read, customer_read
organization cid
The sid can be used to retrieve a large number of results from a search request. Read the full docs to learn how to use the sid
Number of Contacts returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
Return Contacts with email
Return Contacts with an email verified
Return Contacts with phone number
Return Contacts with an phone number verified
Return Contacts with the requested signup method
Return Contacts registered on specific locations
Return Contacts belonging to specific segment or segments (comma separated)
Return Contacts with creation date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return Contacts with creation date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return Contacts with modified date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return Contacts with modified date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z
Return Contacts with marketing communication opt-in with value true
Return Contacts with age verification set to true
Return Contacts with specific custom opt-ins set to true. Eg: customOptin.my_policy=true
firstName, lastName, gender, birthDate, country, created, privacy, termsOfUse, mktgCommunications, ageVerification, phone, phoneVerified, email, emailVerified, provider, username, locked, locations, system, enabled, type, modified_absolute,created_absolute,totalVisits,visitedLocations
Reverse sort order. sortBy argument is required
Search by email address
Search by phone number
Search by username
Search by external Id
Search by external property 1
Search by external property 2
The array of the customers
id used in the scrolling
customer cid