Unifi OS

The Hudu and UniFi OS integration automatically syncs your UniFi network data into Hudu using Ubiquiti's official API, helping keep device inventories and infrastructure documentation accurate, organized, and up to date.

What you'll need

• One or more UniFi API keys, generated from your Ubiquiti account.
• An Admin or Super-Admin user role within Hudu.

What this integration syncs

The UniFi OS integration can sync the following into Hudu:

• UniFi-provided devices — pulls device information from UniFi into an asset layout.
• Client devices — pulls client device information from UniFi into an asset layout.
• Guest devices — pulls guest device information from UniFi into an asset layout.
• Networks — syncs each network and adds it to the IPAM component of the matched company.

Setting up the integration

To enable the integration, navigate to the Hudu admin area (Admin → Integrations) and select UniFi OS from the list.

Step 1. Enter your credentials

• Enter your UniFi API key. This field is required and cannot be left empty.
• To sync data across more than one UniFi account, add additional API keys. Keys can be added, saved, and removed at any time.

Step 2. Test the Connection

• Once the test connection is successful, you will automatically be moved to the next step to activate and sync the integration.

Step 3. Activate and Sync

• Activate and sync the integration to begin pulling over companies. 
  • Sync time may vary, depending on the amount of data.
• You may navigate away from this page while sync is in progress.

Step 4. Options

In the Options section, customize which items you'd like to sync, what information you'd like Hudu to update, and how you'd like Hudu to match assets.

Options:

• Auto-update names of assets — automatically sync asset names from UniFi to keep them current.
• Do not update basic company details — this includes company type, sync status, and the company active/inactive state.
• Match assets on primary serial — if checked, assets will only be matched if both the asset name and primary serial number match.

Skip the following

• Check any data type you don't want to bring into Hudu:
  • Inactive companies (will be checked by default)
  • UniFi provided devices
  • Client devices
  • Guest devices
  • Networks
• Click Save Options to move to the next step.

Step 5. Device Types

The Device Types section lets you skip specific device types. The device types listed reflect what's found in your UniFi data.

• Skip the following UniFi provided device types — for example, accessPoint, gateway, and switching.
• Skip the following client/guest device types — for example, teleport, vpn, wired, and wireless.
• Click Save Device Types to move to the next step.

Step 6. Match your companies

• Match at least one company, then select Sync Now to complete the set up.
  • Companies are organized under Unmatched and Matched tabs, and can be filtered by All match types, Suggested matches, and No suggested matches.
  • Match each UniFi company to an existing or new Hudu company. Companies left unmatched, along with their data, are not imported.
  • Hudu recommends matching one company first to confirm data imports correctly before matching the rest.

Step 7. Asset Layouts

• Select the asset layouts you'd like Hudu to use for each category below, then re-sync the integration to complete set up.
  • In the Asset Layouts section, select a default asset layout for each category: UniFi Devices, Client Devices, and Guest Devices. Each is required.
  • Use Add Sort Rule to create additional rules that better organize your configurations or create exceptions to the defaults above.
  • Click Save Asset Layouts when you're done.

Step 8. Run a sync

After matching your companies and setting your asset layouts, click Sync Now to bring in your devices and networks. Networks are added to the IPAM component of their matched company.

How Hudu names your UniFi sites

When you connect UniFi OS, Hudu imports your sites so you can match them to companies in Hudu. The name Hudu displays for each site depends on how the console is set up.

Consoles with more than one site — Hudu shows the site name as it appears in UniFi.

Consoles with a single site — Hudu shows the console name instead.

The reason for the difference is that UniFi only offers a site rename option when a console has more than one site. On a single-site console, the site is always named "Default" and there is no way to change it. If Hudu displayed that name, every single-site console in your account would appear as "Default" with no way to tell your clients apart. Using the console name — the name you already gave it in UniFi — keeps each one identifiable.

Changing the name Hudu displays

For a single-site console, rename the console in UniFi Site Manager under Control Plane → Console. Keep in mind that this also renames that device in your UniFi device list.

For a console with multiple sites, rename the site itself in the UniFi Network application.

Either way, the updated name appears in Hudu after the next sync.

Renaming is safe

Hudu tracks each site by a permanent internal ID rather than by its name. Renaming a site or console in UniFi will not break an existing match or interrupt device syncing — the name shown in Hudu simply updates on the next sync.

FAQ

Troubleshooting