1. Home
  2. Knowledge Base
  3. Supported Hardware
  4. Ubiquiti
  5. Ubiquiti Unifi API Configuration Guide

Ubiquiti Unifi API Configuration Guide

The following instructions outline how to setup your Ubiquiti UniFi network to GoZone’s Marketing 4 WiFi platform. This guide assumes your Unifi controller is already operational on a live network with adopted Access Points. You will need access to the Marketing 4 WiFi dashboard and admin access to the Unifi controller to complete this guide.

Firewall Considerations

If your Unifi Controller is not publicly accessible you must set up port forward and/or firewall rules to allow communication to the Unifi controller’s internal LAN IP from the platform’s public IP addresses based on your environment using protocol TCP and destination port 8443 (if using Unifi software controller) or 443 (if using a Unifi console).

The following table shows the IP addresses that the Marketing 4 WiFi platform could use to make outbound connections to the Unifi controller.

US-AUS-B
52.23.46.1393.132.31.3
52.207.192.2433.18.137.68
18.233.247.33.13.114.17

Marketing 4 WiFi Dashboard Setup

Adding Gateways to your Hotspot

The MAC of every access point that broadcasts the Guest WiFi must be added to your hotspot.

  1. Login to your Marketing 4 WiFi dashboard
  2. Using the navigation panel to the left, select Network> Gateways
  3. Click the Add Gateway option to the top right
    1. Select Hotspot: Select your desired hotspot
    2. Gateway Name: Enter a name for this Gateway(s)
      1. Gateway Type: Ubiquiti Unifi API
      2. MAC Address: Enter the MAC Address of your Unifi AP. (use the blue + icon to the right to add multiple AP MACs at once)
      3. Unifi Connection Terminate:Enabling the Unifi Connection Terminate toggle will result in the platform polling the Unifi controller every 15 minutes and de-authorizing any active session if the device MAC is no longer associated to the wireless network with a reason for termination as Lost Carrier.
      4. Portal URL: Enter your Unifi controller public IP or valid hostname
      5. Username: Enter the username of a local site admin on the Unifi controller (Not a Unifi Cloud account)
      6. Password: Enter the password for the username of the local site admin on the Unifi controller entered above
      7. Click the ‘Test Unifi API Settings’ button to test the platform communication to your Unifi controller.
        If successful move on to the next step, if not confirm your values for Portal URL, Username, Password, and that any firewall rules have been properly configured.
      8. Select the correct Site after the field populates from the successful use of the Test Unifi API Settings button.
    3. Press Submit
    4. This completes the Gateway creation portion of this guide

Confirming Platform Details

To complete the hardware configuration  you must obtain details unique to your Operator environment and desired hotspot.

  1. Login to your Marketing 4 WiFi dashboard
  2. Using the navigation panel to the left, select Operator Settings > Operator Customizations
    1. Splash Hostname: This is your splash hostname for use later in this guide
    2. Platform Environment: Confirm your environment to ensure you have the correct Firewall rules in place


  1. Login to your Unifi controller and select the correct site
  2. On the menu to the left, click the Settings option
  3. On the WiFi Tab, click Create New or Edit your existing Guest WiFi
    • Hotspot Portal: Checked
    • Set all other options to best practices
    • Press Add WiFi Network (or Apply Changes)
  4. On the menu to the left, click the Hotspot Manager option
  5. Click the Landing Page tab at the top of the page
  6. Using the menu panel to the right, on the Branding tab configure with
    • Success Landing Page: Use the Splash Hostname collected in Step 2.1 of the Confirming Platform Details section of this guide and add “/hotspotlogin.php?res=success” to the end.
      Example- https://splash.4wifi.net/hotspotlogin.php?res=success
  7. Using the menu panel to the right, on the Authentication tab configure with
    • External Portal Server: Enabled
    • External Portal: 8.8.8.8
  8. Using the menu panel to the right, on the Settings tab configure with
    • Show Landing Page: Checked
    • HTTPS Redirection Support: Unchecked
    • Encrypted URL: Checked
    • Secure Portal: Checked
    • Domain: Use the Splash Hostname collected in Step 2.1 of the Confirming Platform Details section of this guide without the scheme at the begginging
      Example- splash.4wifi.net
    • Pre-Authorization Allowances: Add the value you used for the Domain as well the platform Default walled garden entries.
  9. Press Save

  1. Launch the correct site in your Unifi controller and click the settings icon in the bottom left.
  2. On the menu to the left click Profiles.
  3. Click on the Default option under the Guest Hotspot section and configure with the following settings:
    • Authentication Type: External Portal Server
    • External Portal: 8.8.8.8
    • Guest Landing Page: ON
    • Advanced: Manual
    • Landing Page: Use the Splash Hostname collected in Step 2.1 of the Confirming Platform Details section of this guide and add “/hotspotlogin.php?res=success” to the end.
      Example- https://splash.4wifi.net/hotspotlogin.php?res=success
    • Redirection-
      1. Enabled HTTPS Redirection: Unchecked
      2. Enable encrypted redirect URL: Unchecked
      3. Use Secure Portal: Checked
      4. Redirect Using Hostname: Checked
        • Use the Splash Hostname collected in Step 2.1 of the Confirming Platform Details section of this guide without the scheme at the begginging
          Example- splash.4wifi.net
      5. Allowed Authorization Access: Add all the Default walled garden entries.
  4. On the menu to the left click Wireless Networks.
  5. Create a new Wireless Network or Edit your existing Guest WiFi network.
      • WiFi Type: Guest Hotspot
      • Set all other options to best practices
      • Press Apply Changes to save.

Troubleshooting Splash page

  1. If devices are redirected but the device hangs on the controller url please ensure port 8880 is open to the Unifi Controller.
  2. If devices present an certificate error please ensure https redirection is disabled.
  3. If a hotspot deactivated message is presented please ensure all the AP MACs have been added as gateways to the correct hotspot.
  4. If devices are redirected to the splash page URL but the page fails to load please ensure the Allowed Authorization Access list has been properly configured.

Disclaimer on hardware configuration guides in the KB:

This equipment has been integrated and tested in our labs with the Marketing4WiFi platform using the firmware versions below.

Ubiquiti UniFi CloudKey Version 7.2.92-18687-1 Firmware 1.1.19
Ubiquiti UniFi UAP-AC-Lite 6.0.21.13673

LIMITED HARDWARE SUPPORT: Hardware manufacturers frequently make changes to firmware, controllers and GUI’s. The information below may be out of date or images may be different and is to be used as a general reference guide. We do offer additional limited support to help with trouble-shooting and we highly recommend that you have a hardware support agreement and/or access to a hardware support engineering representative from the manufacturer.

Updated on July 3, 2024
Was this article helpful?

Related Articles

Need Support?
Can't find the answer you're looking for? Don't worry we're here to help!
CONTACT SUPPORT