Query Halo Clients
The Query Halo Clients action finds clients and companies in Halo PSA. It can return the first match or an array containing up to 100 matches.
This action searches only the first result page and applies every configured filter in Halo.
When to Use This Action
Use this action when you need to:
- Find a client ID for another Halo action
- Match clients by name, parent client, domain, activity, or another standard filter
- Filter clients with Halo Custom Fields
- Retrieve all fields available in Halo's client list response, including notes when Halo provides them, plus all readable Custom Fields
Do not use this action to retrieve more than 100 clients. Narrow the filters or use Halo's API directly when you need later pages.
How It Works
The action first checks which Client Custom Fields your Halo connection can read. It then asks Halo for page 1 with those Custom Fields. Halo also returns the standard client fields available from its list response. This can include notes, but Halo may omit optional properties from individual clients.
The default order is Client ID from lowest to highest. In First match mode, a non-Continue multiple-results choice makes the action request two clients so it can check uniqueness.
The action counts clients returned on page 1 rather than Halo's reported total. It stores a successful result before applying a result-count choice. A request error or malformed response uses Error Handling, clears the result to null, and does not trigger a no-results choice.
Configuration
Results
| Field | Description | Default |
|---|---|---|
| Results | Return Up to 100 matches as an array, or First match as one object or null. | Up to 100 matches |
| Order By | Sort by Client ID or Name. | Client ID |
| Order Descending | Reverse the selected order. | Disabled |
Search and filters
| Field | Description |
|---|---|
| Search | Search Halo's client fields. |
| Search Name Only | Search client names only. |
| Parent Client | Return clients belonging to the selected parent client. |
| Ticket Area ID | Filter by an exact Halo ticket area ID. |
| Domain | Filter clients by domain. |
| Active State | Return active clients, inactive clients, or both. |
| Account Manager Only | Return only clients managed by the current Halo agent. |
| Exclude Internal | Exclude internal clients. |
| Custom Field Filters | Build grouped AND/OR conditions using Halo Client Custom Fields. |
Error Handling
| Field | Description |
|---|---|
| Error Handling | Choose what happens when either Halo request fails or returns malformed data. Available choices depend on the type of automation. |
| If no results are returned | Choose what happens after a successful query returns no clients. |
| If more than one result is returned | Choose what happens after a successful query returns multiple clients. A non-Continue choice enables a two-client uniqueness check in First match mode. |
Returned Variables
In First match mode, the stored result is one client object or null. In Up to 100 matches mode, the result is an array capped at 100 clients, including [] when no client matches.
Common properties include .id, .name, .toplevel_id, .main_site_id, .inactive, .phone, .email, .website, and .customfields. Halo also returns .notes when notes are available for that client. Optional properties may be absent.
For the first result in array mode, use a value such as {{custom.clients.[0].id}}.