HaloPSA Complete icon

HaloPSA Complete

Get data from the HaloPSA API

Actions68

Overview

The "Agent - Get Many" operation in this node retrieves multiple agent records from the HaloPSA API. It is designed to fetch a list of agents with extensive filtering, sorting, and pagination options. This operation is useful when you need to obtain detailed or summarized information about agents in your organization, such as for reporting, synchronization, or automation workflows.

Practical examples include:

  • Fetching all active agents who belong to a specific department.
  • Retrieving a limited number of agents with certain qualifications or roles.
  • Getting agents filtered by their online status or integration type.
  • Including additional metadata like team membership, roles, or ticket counts for each agent.

Properties

Name Meaning
Return All Whether to return all results or only up to a given limit.
Limit Maximum number of results to return (used if Return All is false).
Filters Collection of filters to narrow down the agents returned. Includes:
  Active Inactive Comma-separated values to include active and/or inactive agents.
  Appointment Screen Filter for agents designated for appointment screens.
  Basic Fields Only Reduce the number of fields returned for each agent.
  Can Edit Only Filter agents that the user has permission to edit.
  Client ID Filter agents belonging to a particular client by ID.
  Client ID Override Override client ID for filtering purposes.
  Department ID Filter agents belonging to a specific department by ID.
  Departments Comma-separated list of departments to filter agents by.
  Domain Filter on agent permissions domain: Opportunities, Projects, or Requests.
  Exchange Calendars Filter agents that have Exchange calendars synced.
  Exclude Agent Exclude an agent by specified ID.
  Exclude Membership Info Remove team and department membership info from response.
  Force Qual Match Force qualification match filtering.
  Include API Agents Include API agents in the response.
  Include Disabled Include inactive agents in the response.
  Include Enabled Include active agents in the response.
  Include Membership Info Always include team and department membership info.
  Include Named Count Include count of the number of agents in the response.
  Include Roles Include agent roles in the response.
  Include Status Include agent status in the response.
  Include Unassigned Include the unassigned agent in the response.
  Integration Type Filter agents by integration type (e.g., Okta).
  Is Agent Cache Use special behavior for agent app cache build.
  Line Managed Only Filter agents that have a line manager.
  Linking Agents Filter for linking agents.
  Load Cache Load cache option.
  Online Statuses Comma-separated list of online statuses to filter agents by.
  Order Field to order results by (primary).
  Order 2 Second field to order results by.
  Order 3 Third field to order results by.
  Order 4 Fourth field to order results by.
  Order 5 Fifth field to order results by.
  Order Desc Whether to order primary field descending.
  Order Desc 2 Whether to order second field descending.
  Order Desc 3 Whether to order third field descending.
  Order Desc 4 Whether to order fourth field descending.
  Order Desc 5 Whether to order fifth field descending.
  Page Number Page number for pagination.
  Page Size Page size for pagination.
  Paginate Whether to paginate results.
  Qualifications Comma-separated list of qualifications to filter agents by.
  Reassign Filter agents that can assign tickets in sections they are not members of.
  Remote Agent Type Filter on agent invite permissions by remote agent type (BeyondTrust or LogMeIn).
  Remote Agents Filter on agent invite permissions.
  Role Filter agents by role (requires integer passed as string).
  Search Search filter by name, email, or telephone number.
  Shift Agents Only Filter for shift agents only.
  Show All Override organization restrictions for main search (admin only).
  Show Counts Include agent ticket counts in the response.
  Team Filter agents within a particular team by name.
  Team ID Filter agents within a particular team by ID.
  Teams Comma-separated list of teams to filter agents by.
  This Agent Only Include only the current user’s agent in the response.
  Ticket Area ID Ticket area filter (only used when Show Counts is true).
  Ticket Type ID Filter agents that have access to particular ticket types.
  View ID Ticket view filter (only used when Show Counts is true).
  With Email Filter agents that have an email address.

Output

The output JSON contains an array of agent objects matching the applied filters and pagination settings. Each agent object may include:

  • Basic agent details such as name, email, phone number, status, and roles.
  • Optional membership information including teams and departments if requested.
  • Ticket counts and other statistics if enabled.
  • Additional metadata depending on the filters and flags set (e.g., qualifications, online status).

If binary data were involved (not indicated here), it would typically represent attachments or files related to agents, but this operation focuses on JSON data.

Dependencies

  • Requires connection to the HaloPSA API with valid authentication credentials (an API key or token).
  • The node expects the HaloPSA API endpoint to be accessible and properly configured.
  • No other external services are explicitly required.

Troubleshooting

  • Common Issues:

    • Incorrect or missing API credentials will cause authentication failures.
    • Using invalid filter values (e.g., non-existent department IDs) may result in empty responses.
    • Pagination parameters must be consistent; requesting pages beyond available data returns empty sets.
    • Overly broad queries without limits may lead to large data loads and timeouts.

  • Error Messages:

    • Authentication errors indicate invalid or expired API keys; verify and update credentials.
    • Validation errors on filters suggest incorrect parameter formats; check input types and allowed values.
    • Network or timeout errors imply connectivity issues; ensure the API endpoint is reachable.

  • Resolution Tips:

    • Double-check all filter inputs for correctness.
    • Use the "Return All" flag carefully to avoid performance issues.
    • Confirm API credentials and permissions.
    • Review API documentation for any changes in supported parameters.

Links and References

Discussion