Ubiquiti Unifi API Configuration

Why upgrade to the new Unifi API Integration?

With the Unifi API Integration your hotspots can fully utilize advanced login features like Guest Plans or Ad-Based login and provide guests the correct rate-limiting settings for the method used.

You can confirm your environment under Operator Customizations.

Checklist before proceeding with the Unifi configuration

  1. If you are running UniFi 6.0 or higher you need to disable the new UI to complete this configuration guide. To do so, click Settings then System on the left menu and enable Legacy Interface option.
  2. Please ensure the necessary ports are open to the controller per Unifi documentation, including port 8880 and 8443 both directions or guest devices will be unable to load the splash page.
  3. The MAC of all APs that will be broadcasting the Guest WiFi signal need to be properly added to the hotspot as Ubiquiti Unifi API gateways or guests could receive a hotspot deactivated message.

The following instructions outline how to setup a Ubiquiti UniFi network for the Marketing4WiFi Platform utilizing the API integration. This guide assumes that your Unifi controller is already operational and on a live network with adopted Access Points. Please make sure any firewall rules, web content filters, and other security measures have been configured to interface with the platform.

    1. Add your Ubiquiti Unifi Access Points to the Marketing4WiFi Dashboard using the Ubiquiti Unifi API gateway type. You will need to enter a portal URL where the controller can be reached as well as a valid Administrator Username and Password before pressing ‘Test API Credentials’ to generate a list of possible sites to select from. Be sure to Submit the page!
      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.

    2. Log into the controller.
    3. Launch the correct site and click the settings icon in the bottom left.
    4. On the menu to the left click Guest Control and configure with
      • Enable Guest Portal: Checked
      • Authentication: Hotspot
      • Promotional URL: Select one
        US-A Redirect URL


        You can confirm your platform environment under Operator Customizations.

        If you have your own branded splash hostname you would use https://splash.yourdomain.com/hotspotlogin.php?res=success

        US-B Redirect URL


        You can confirm your platform environment under Operator Customizations.

        If you have your own branded splash hostname you would use https://splash.yourdomain.com/hotspotlogin.php?res=success

      •  Redirection-
        1. Use Secure Portal: Unchecked
        2. Redirect Using Hostname: Unchecked
        3. Enabled HTTPS Redirection: Unchecked
        4. Enable encrypted redirect URL: Unchecked
      • Template Engine: Angular JS
      • Override Default Templates: Checked
      • Pre-Authorization Access: Add all the Default walled garden entries.

        If you’re a white label client and you have your own splash domain, be sure to include it in the walled garden.

      • Press ‘Apply Changes’ to save.
    5. On the menu to the left click Wireless Networks.
      • Create a new Wireless Network or Edit your existing Guest WiFi network.
      • Check the Guest Policy box to enable the Guest Control settings.
    6. Final Step- Place the two HTML files from your dashboard’s Ubiquiti Unifi API gateway page onto your Unifi controller hotspot directory for the site code used in step one.

      If your splash hostname changes you must update these two files as well as your pre authorization access list.

      Typical file location examples are below.(depending on the UniFi controller):
      Please note you will typically use your site auto generated folder name instead of default.
      Dream Machine: /data/unifi/data/sites/default/app-unifi-hotspot-portal
      CloudKey: /srv/unifi/data/sites/default/app-unifi-hotspot-portal
      Windows: C:\Users\<username>\Ubiquiti UniFi\data\sites\default\app-unifi-hotspot-portal
      MAC: ~/Library/Application Support/UniFi/data/sites/default/app-unifi-hotspot-portal
      Linux: /usr/lib/unifi/sites/data/default/app-unifi-hotspot-portal

Platform IP Addresses for Unifi API Integration

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


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 are redirected and port 8880 is open to the controller please ensure that the ‘Secure Portal’ option is turned OFF.
  3. If devices present an certificate error please ensure https redirection is disabled.
  4. If a hotspot deactivated message is presented please ensure all the AP MACs have been added as gateways to the correct hotspot.
  5. 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.
  6. If the internal captive portal from the Unifi controller is displayed instead of the hotspot splash page make sure ‘Override Default Templates’ is ON and the index and auth files have been placed on the correct site directory.

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

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 August 29, 2022

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!