Guest voucher management tools reference

Hotspot vouchers are single-use or limited-use access codes you hand to guests so they can connect to your Wi-Fi without sharing your main network password. Each voucher grants access for a fixed duration and can optionally cap bandwidth or total data usage. The tools below let your AI assistant generate, inspect, and clean up vouchers without you touching the UniFi console.

Voucher management requires the guest portal on your site to be configured with auth_method set to voucher. See the RADIUS and guest portal tools reference for portal configuration.

Tools

`list_vouchers`

Returns all hotspot vouchers for a site. Supports pagination and optional filtering to narrow results by status or expiry.

string

required

The site identifier.

integer

Maximum number of vouchers to return per request.

integer

Number of vouchers to skip, for paginating through large sets.

string

A filter expression to narrow results (e.g., filter by note or status).

Example response

[
  {
    "id": "vchr-abc123",
    "code": "ABCD-1234",
    "duration": 3600,
    "note": "Conference room day pass",
    "used": false,
    "created": "2025-11-01T09:00:00Z"
  }
]

`get_voucher`

Returns the details of a single voucher by its ID.

string

required

The site identifier.

string

required

The voucher identifier.

`create_vouchers`

Creates one or more vouchers in a single call. All vouchers created in a batch share the same settings.

string

required

The site identifier.

integer

required

How many vouchers to generate. Use 1 for a single code, or a higher number to generate a batch (e.g., for a conference).

integer

required

How long each voucher grants access, in seconds. For example: 3600 = 1 hour, 86400 = 1 day, 604800 = 7 days.

integer

Upload speed cap per voucher user, in kilobits per second. Omit for unlimited upload.

integer

Download speed cap per voucher user, in kilobits per second. Omit for unlimited download.

integer

Total upload data allowed before the voucher expires, in megabytes. Omit for unlimited.

integer

Total download data allowed before the voucher expires, in megabytes. Omit for unlimited.

string

An administrative label attached to all vouchers in this batch (e.g., "Staff training day 2025-11-15"). Helpful for bulk deletion later.

boolean

required

Must be true to create the vouchers.

boolean

When true, returns the payload that would be submitted without creating any vouchers.

{
  "site_id": "default",
  "count": 10,
  "duration": 28800,
  "download_limit_kbps": 10000,
  "upload_limit_kbps": 5000,
  "note": "All-hands conference 2025-11-20",
  "confirm": true,
  "dry_run": true
}

{
  "site_id": "default",
  "count": 10,
  "duration": 28800,
  "download_limit_kbps": 10000,
  "upload_limit_kbps": 5000,
  "note": "All-hands conference 2025-11-20",
  "confirm": true
}

Example response

{
  "success": true,
  "count": 10,
  "vouchers": [
    { "id": "vchr-001", "code": "WXYZ-4321", "duration": 28800 },
    { "id": "vchr-002", "code": "MNOP-8765", "duration": 28800 }
  ]
}

`delete_voucher`

Permanently deletes a single voucher by its ID. If a guest is currently using the voucher, they will lose access.

string

required

The site identifier.

string

required

The ID of the voucher to delete.

boolean

required

Must be true to delete the voucher.

boolean

Preview the deletion without applying it.

`bulk_delete_vouchers`

Deletes all vouchers that match a filter expression. Use this to clean up expired or event-specific batches.

string

required

The site identifier.

string

required

A filter expression that selects the vouchers to delete (e.g., filter by note to target a specific batch).

boolean

required

Must be true to execute the bulk deletion.

boolean

Preview which vouchers would be deleted without removing them.

bulk_delete_vouchers will remove all vouchers that match the filter — including any that are currently in use. Always use dry_run=true first to confirm the scope of deletion.

Example: generating conference day-pass vouchers

This example generates 25 vouchers for a day-long event, each capped at 20 Mbps download and 5 Mbps upload. After the event, the entire batch is cleaned up.

# Step 1: Preview the batch
create_vouchers(
    site_id="default",
    count=25,
    duration=86400,          # 24 hours in seconds
    download_limit_kbps=20000,
    upload_limit_kbps=5000,
    note="Tech Summit 2025-11-20",
    confirm=True,
    dry_run=True
)

# Step 2: Create the vouchers
result = create_vouchers(
    site_id="default",
    count=25,
    duration=86400,
    download_limit_kbps=20000,
    upload_limit_kbps=5000,
    note="Tech Summit 2025-11-20",
    confirm=True
)

# Step 3: After the event, clean up (dry run first)
bulk_delete_vouchers(
    site_id="default",
    filter_expr="note:Tech Summit 2025-11-20",
    confirm=True,
    dry_run=True
)

# Step 4: Confirm and execute the cleanup
bulk_delete_vouchers(
    site_id="default",
    filter_expr="note:Tech Summit 2025-11-20",
    confirm=True
)

Always attach a descriptive note when creating event-specific batches. It makes filtering and bulk deletion much easier when the event ends.

Overview

Read Operations

Write Operations

Security & Access

Operations

Guest voucher management tools reference

Tools

`list_vouchers`

`get_voucher`

`create_vouchers`

`delete_voucher`

`bulk_delete_vouchers`

Example: generating conference day-pass vouchers

​Tools

​list_vouchers

​get_voucher

​create_vouchers

​delete_voucher

​bulk_delete_vouchers

​Example: generating conference day-pass vouchers

Tools

`list_vouchers`

`get_voucher`

`create_vouchers`

`delete_voucher`

`bulk_delete_vouchers`

Example: generating conference day-pass vouchers