Query Halo Clients
The Query Halo Clients action searches and filters clients/companies in Halo PSA. Use this to find clients by name, domain, or other criteria.
This is a single API call action. You define the search and filter conditions and the action makes one API call to retrieve the results. Learn more about the difference between workflow actions and single API call actions.
When to Use This Action
Use this action when:
- You need to find a client by name, domain, or other criteria
- You want to retrieve a client ID for use in a subsequent Create Halo Ticket action
- You need to verify whether a client exists before performing other operations
Configuration
Connection
| Field | Description |
|---|---|
| Halo Connection | Select the Halo connection to use for this action. |
Search & Pagination
| Field | Description | Default |
|---|---|---|
| Search | Search term to filter clients by name. Supports text expressions. | None |
| Search Name Only | Search only by client name (more specific than general search). | Disabled |
| Advanced Search | Raw Halo advanced search expression for expert use. Do not combine it with Custom Field Query. Supports text expressions. | None |
| Page Size | Number of results per page (1-1000). | 25 |
| Page Number | Page number to retrieve. | 1 |
Filters
| Field | Description |
|---|---|
| Parent Client | Filter clients by parent/top-level client. |
| Ticket Area ID | Filter by ticket area ID. |
| Domain | Filter clients by domain. Supports text expressions. |
Status Filters
| Field | Description | Default |
|---|---|---|
| Include Active | Include active clients in results. | Enabled |
| Include Inactive | Include inactive clients in results. | Disabled |
| Account Manager Only | Only return clients where you are the account manager. | Disabled |
| Exclude Internal | Exclude internal clients from results. | Disabled |
Ordering
| Field | Description |
|---|---|
| Order By | Field name to order results by (e.g., name, id). |
| Order Descending | Sort results in descending order. |
Response Options
| Field | Description |
|---|---|
| ID Only | Return only ID fields. Not compatible with pagination. |
| Include Notes | Include client notes in the response. |
| Include Custom Fields | Select custom fields to include in each returned client. The saved value remains a comma-separated string of field IDs for compatibility with existing workflows. |
Custom Field Filters
| Field | Description |
|---|---|
| Custom Field Query | Build a schema-aware filter from Halo client custom fields. Available fields and operators come from Halo metadata. Unlocked text values support text expressions. |
Use either Advanced Search or Custom Field Query, not both. The action rejects configurations that combine them. A flat AND custom field query becomes Halo advanced_search; supported OR groups become advanced_search_group.
Error Handling
| Field | Description |
|---|---|
| Error Handling | Action to take if the query fails (Exception, Continue, Stop, Stop All). |
Returned Variables
When you configure Store the results in Variable, these variables become available for use in subsequent actions:
| Variable | Type | Description |
|---|---|---|
record_count | number | Total number of matching clients |
clients | array | Array of client objects |
When you select Include Custom Fields, each returned client can include a customfields array. Each item contains id (the Halo custom field ID) and value (the returned value).
Client Properties
Each client in the clients array contains:
| Property | Type | Description |
|---|---|---|
id | number | The client ID |
name | string | The client name |
toplevel_id | number | Parent client ID (if applicable) |
main_site_id | number | Main site ID |
inactive | boolean | Whether the client is inactive |
phone | string | Primary phone number |
email | string | Primary email address |
website | string | Website URL |
notes | string | Client notes (if Include Notes is enabled) |
Example usage: {{custom.myVariable.clients.[0].id}}
Example Use Cases
Find Client by Domain
Set the Domain filter to match the email sender's domain:
| Setting | Value |
|---|---|
| Domain | {{email.from.domain}} |
Search by Name
| Setting | Value |
|---|---|
| Search | {{custom.companyName}} |
| Return first result only | Leave Page Size at 1 |
Check If a Client Exists
Query for the client and then check if record_count is greater than 0 in a subsequent conditional action.
FAQs
How do I use the client ID in a subsequent action?
Store this action's result in a variable (e.g., clients), then reference {{custom.clients.clients.[0].id}} in the next action.
Why might my search return no results?
The search is partial-match by name. If the Domain filter is set, it performs an exact match. Ensure the domain value matches the format stored in Halo.
Related Actions
- Query Halo Users: Find users/contacts for a client
- Query Halo Tickets: Find tickets for a client
- Create Halo Ticket: Create a ticket for the found client