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.
Visit Understanding Integrations for basic concepts and useful tips before setting up this integration.
UniFi OS is a separate integration from UniFi (self-hosted). Use UniFi OS to connect through Ubiquiti's API with an API key. If you manage a locally hosted UniFi Network controller, use the UniFi (self-hosted) integration instead.
What you'll need
- One or more UniFi API keys, generated from your Ubiquiti account.
- An Admin or Super-Admin user role within Hudu.
You can return to your Hudu admin area → Integrations → UniFi OS at any time to make changes to the integration.
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.
Client and guest devices are related to the network they belong to. UniFi-provided devices are synced as assets but are not related to the network.
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. Set your options
In the Options section, choose how you want the integration to behave, then click Save Options.
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
- UniFi provided devices
- Client devices
- Guest devices
- Networks
Step 3. Map your device types
- The Device Types section lets you skip specific device types within the categories you kept in Step 2. 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.
- During initial setup, if you skip every device category (UniFi provided, client, and guest devices) in Step 2, the Device Types section is skipped and you move directly to the Companies step.
Step 4. Match your companies
- In order to pull over data, UniFi OS must be matched to Hudu companies. Open the Companies section to review your matches.
- 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.
Re-sync the integration any time you make changes in the Companies section.
Step 5. Set your asset layouts
- 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.
Changes in the Asset Layouts section only apply to new data that has not already been synced into Hudu.
Step 6. Run a sync
After matching your companies and setting your asset layouts, run a sync to bring in your devices and networks. Networks are added to the IPAM component of their matched company.
Active integrations re-sync automatically every 3 hours. You can also trigger a manual re-sync from the integration settings page or the re-sync button in the top right of an asset card.
FAQ
UniFi OS connects to UniFi through Ubiquiti's API using an API key, and supports multiple accounts. UniFi (self-hosted) connects directly to a locally hosted UniFi Network controller using a domain, username, and password. Controllers running UniFi OS are not supported by the self-hosted integration, which is why UniFi OS exists as a separate integration.
Native integrations automatically re-sync every 3 hours. You can also run a manual re-sync at any time from the integration settings page or with the re-sync button in the top right.
Yes. In the credentials step you can add multiple API keys. Keys can be added, saved, and removed at any time.
Each synced network is added to the IPAM component of its matched company.
This is expected. UniFi-provided devices are synced as assets but are not related to a synced network. Client and guest devices are related to the network they belong to.
Troubleshooting
Confirm that your API key is entered correctly, is still valid, and has access to the UniFi data you're trying to sync. Re-enter the key if needed and test the connection again.
During initial setup, the Device Types section only appears when at least one device category is kept in the Options step. If you skipped UniFi provided, client, and guest devices, the section is skipped and you're taken directly to the Companies step. Un-check one of those device categories under "Skip the following" to bring it back. Note that when you edit an existing integration, the Device Types section stays visible even if all types are skipped.
Client and guest devices can add a large number of assets. Disable those categories in the Options step to stop syncing them going forward, then archive or clean up the assets that were already brought in.