Guest Wi-Fi That Brings Customers Back: UniFi Captive Portal Marketing for Restaurants and Local Businesses

Step by step: connect your own portal to UniFi

This is the setup from Ubiquiti’s External Hotspot API for Authorization Clients article, written out for a business owner or an IT person. Menu names can differ slightly between UniFi Network versions; the API examples are a sketch to check against the API documentation in your own console.

1. Update UniFi Network and create an API key

• Update the UniFi Network application on your Cloud Gateway to 9.1.105 or newer. This is the version where Ubiquiti published the official API and API keys.
• Open Network → Control Plane → Integrations and create an API key, for example “Guest portal”. The same page has the full API documentation for your version — keep it open.
• Store the key only on the portal server or the connector in your network, never in the portal page or in the browser.

2. Create the guest network and turn on the captive portal

• Create a separate network for guests (its own VLAN) and a Wi-Fi name such as “Harbor Street Guest”.
• Turn on Hotspot → Captive Portal for this Wi-Fi. New phones then join as GUEST with authorized: false and cannot reach the internet yet.
• In the portal settings, under authentication, choose External Portal Server and enter the address of your portal server.
• In Pre-Authorization Access (the “walled garden”), allow the portal’s domain and IP address, plus anything the portal loads before login: fonts, images, a payment page or a sign-in provider.
• Check the firewall: the Hotspot zone is applied to the guest network and guests cannot reach your office network, registers or cameras.

3. Read who is connecting

When a guest opens any page, UniFi sends the phone to your portal with the details in the address:

http://YOUR-PORTAL/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://netcts.cdn-apple.com%2F&ssid=dph-guest

• id — the MAC address of the guest’s phone (the one you will authorize);
• ap — the access point the guest is connected to (useful when you have several rooms or locations);
• ssid — the Wi-Fi name;
• url — the page the guest originally wanted.

The portal now shows your offer, the coupon and the optional e-mail sign-up, and always a “just connect” button.

4. Find the site and the client through the API

The base address and how the API key is sent are listed in the API documentation in your console. On a Cloud Gateway it usually looks like the example below, with the key in the X-API-KEY header.

# the site ID (a Cloud Gateway returns one site)
curl -k -H "X-API-KEY: $UNIFI_API_KEY" \
  "https://192.168.1.1/proxy/network/integration/v1/sites"

# the guest's client record, by the MAC address from the "id" parameter
curl -k -H "X-API-KEY: $UNIFI_API_KEY" \
  "https://192.168.1.1/proxy/network/integration/v1/sites/SITE_ID/clients?filter=macAddress.eq('1c:71:25:63:e4:24')"

The answer contains the client’s id and its access state, for example "access": {"type": "GUEST", "authorized": false}.

5. Let the guest online

When the guest taps “Get my coupon” or “just connect”, the server sends one request. Time, data and speed limits are optional:

curl -k -X POST -H "X-API-KEY: $UNIFI_API_KEY" -H "Content-Type: application/json" \
  "https://192.168.1.1/proxy/network/integration/v1/sites/SITE_ID/clients/CLIENT_ID/actions" \
  -d '{
    "action": "AUTHORIZE_GUEST_ACCESS",
    "timeLimitMinutes": 120,
    "dataUsageLimitMBytes": 500,
    "rxRateLimitKbps": 10000,
    "txRateLimitKbps": 10000
  }'

Then send the guest on: to the page they wanted (url), or better, to your menu, booking page or a “thank you” page with the coupon.

6. Confirm and record

Ask the API for the same client again. When everything worked, it shows "authorized": true with authorizedAt and expiresAt. That is the moment to record the “Wi-Fi authorized” event for the dashboard. If the gateway does not answer, the portal shows a friendly “try again” message and records nothing — it never invents a session.

7. Wired guests (optional)

Guest ports in a lobby or a meeting room can use the same portal: create a wired guest network (for example GuestLAN), put it in the Hotspot zone of the zone-based firewall and assign it to those switch ports.

Test before you launch

• An iPhone and an Android phone, each joining for the first time and again the next day.
• The session runs out: the portal opens again.
• The portal does not pop up by itself: the QR code on the table opens the same page.
• Internet down or gateway restarting: guests see a clear message, the dashboard shows no fake sessions.
• A guest unsubscribes: no more e-mails, and the record of consent is kept.

Not sure about any of these steps? We set it up for you — on your UniFi equipment, with your branding.

Guest Wi-Fi that helps your website and Google listing

Wi-Fi itself does not change where you rank on Google. What it does is put your website and your Google Business Profile in front of every guest at the moment they are happiest with you — sitting at your table or in your chair. That turns into the signals that do matter for local search:

• More Google reviews. The portal and the thank-you e-mail link straight to your review page. Reviews are one of the things Google uses to rank local businesses. One rule: do not trade Wi-Fi or coupons for reviews — Google does not allow incentivized reviews. Ask, do not pay.
• Real visits to your website. The menu, the booking page or the online store open from the portal, tagged so you can see them in your website analytics.
• Your own e-mail list. Opt-in addresses belong to you, not to a delivery app or a social network. Each e-mail with news brings people back to your site.
• QR codes on tables and the counter. Phones do not always open the portal on their own, so a QR code with the offer’s web address works as a second door — and as a printed link to your website.

To make sure your offers reach the inbox and not the spam folder, your domain needs correct SPF, DKIM and DMARC records. You can check them in a minute with our free domain security check.

What the numbers mean — and what they do not

We report only what the network and the portal actually see. When something is unknown, the dashboard says “unknown” instead of guessing.

• Wi-Fi sessions are devices, not people. One guest with a phone and a laptop is two devices; a guest who never connects is not counted at all. We never present Wi-Fi numbers as foot traffic.
• Repeat visits are counted only for guests who chose to sign in. Modern iPhones and Android phones use a private (random) Wi-Fi address, so the same phone can look new on another day.
• Coupons are counted when they are redeemed at the register, which is the most reliable number of all.

Privacy and the rules

• A clear notice on the portal about what is collected and why, with a link to your privacy policy.
• Wi-Fi works without signing up for marketing. The marketing checkbox is separate and never pre-ticked; we store when and how consent was given.
• Marketing e-mails follow CAN-SPAM: who you are, your address and a working unsubscribe link. Text messages need separate written consent and are not part of the basic setup.
• No reading of traffic, no browsing or DNS history, no tracking of phones of people who never connect.
• Data is kept for a set period, can be exported or deleted on request, and every access is logged. Venues for children and healthcare providers get extra review.