Skip to main content

HaloPSA Ticket Integration

Melissa
  • Updated

Team: Huntress Managed Endpoint Detection and Response (EDR)
Integration: Halo (HaloPSA and HaloITSM)
Environment: Huntress Dashboard and Halo (Admin)
Summary: How to connect Huntress to Halo so that Huntress notifications create and update Halo tickets, including the Halo-side settings that affect ticket creation.

In this article

Which Halo products this works with

This integration works with both HaloPSA and HaloITSM. The two products share the same API and the same administration screens, so the setup steps are the same.

Where they differ, this article calls it out. The main differences:

  • Hostname: HaloPSA instances are usually yourcompany.halopsa.com. HaloITSM instances are usually yourcompany.haloitsm.com.
  • Terminology: HaloPSA calls them Clients. HaloITSM calls them Customers. This article says Clients throughout.

The Halo screenshots in this article were taken in HaloPSA. The equivalent HaloITSM screens are the same.

What this integration does

Once the integration is connected, Huntress will:

  • Create a Halo ticket when Huntress sends a notification. You choose which notification types are sent: Incidents, Escalations, Platform Actions, and Account Notices.
  • Post updates onto that same ticket as the notification progresses.
  • Optionally move the ticket to a status you choose when the Huntress notification is resolved.

Tickets are created against the Halo Client mapped to the Huntress organization, using the Ticket Type you select. Huntress also stamps each ticket with the Huntress record type and ID in custom fields, so the ticket can be tied back to the Huntress notification.

Before you begin

You will need:

  • Halo administrator access, sufficient to create an API application and edit Ticket Types.
  • Permission to add integrations in the Huntress dashboard.
  • A decision on which Halo Ticket Type Huntress should use.
  • If your Halo instance restricts access by IP address, allowlist the Huntress IPs before you start. See our Required Firewall Settings article for the full list.

Note: Use the base Halo domain, for example yourcompany.halopsa.com or yourcompany.haloitsm.com. Custom domains are not supported.

Step 1: Configure Halo

Complete all of Step 1 in Halo before you open the Huntress form. You will finish this step holding three values: a hostname, a Client ID, and a Client Secret.

1a. Create a role for Huntress

The agent Huntress signs in as takes its permissions from a role, so create the role first. Halo does not expose the permission settings until the role has been saved once, so this is a two-pass process.

  1. Go to Configuration > Teams & Agents > Roles and create a new role named Huntress.
  2. Click Save.
  3. Open the Permissions tab and click Edit.
  4. Set:
    • Tickets Access Level: Read and Modify
    • Customers Access Level: Read Only. Some instances label this Clients.
    • Can add new Tickets: Yes
    • Can view Unassigned Tickets: Yes
    • Can view Tickets that are assigned to other Agents: Yes
    • Allow use of all Ticket Types: Yes
  5. Confirm the role is not restricted to a subset of teams or clients. A team-scoped or client-scoped role cannot read back the tickets Huntress creates.
  6. Click Save.

HaloPSA_1a.png

1b. Create an API-only agent

  1. Go to Configuration > Teams & Agents > Agents and create a new agent.
  2. On the Details tab:
    • Name the agent Huntress.
    • Select Is an API-only Agent.
    • Under Roles, assign the Huntress role from step 1a.
    • Set Default Team to No Default Team.
  3. Click Save. The remaining tabs appear once the agent exists.
  4. On Departments & Teams, add every team Huntress tickets could land in under Teams, and set Membership level to all Departments to Modify All. Missing this is the most common cause of tickets being created but then invisible to Huntress.
  5. On Client Restrictions, confirm the list is empty.
  6. Leave the Permissions tab alone. The role supplies the permissions, and settings here override it.
  7. Click Save.

HaloPSA_1b.png

1c. Create the API application

  1. In Halo, go to Configuration > Integrations > HaloPSA API. On HaloITSM this reads HaloITSM API.
  2. Click View Applications, then click New.
  3. On the Details tab:
    • Enter an Application Name, for example Huntress.
    • Description is optional and can be left blank.
    • Set Authentication Method to Client ID and Secret (Services). This is the only method the Huntress integration supports.
    • Confirm Active is checked.
  4. Copy the Client ID and Client Secret now, before you save. Halo shows the secret only once. If you lose it you must click Generate to create a new one, which stops the old secret from working.
  5. Set Login Type to Agent.
  6. Set Agent to log in as to the API-only agent you created in step 1b.
  7. On the Permissions tab, tick all. Halo warns that all exposes administration-level access, but the application can only ever do what the Huntress role from step 1a allows, which is where access is actually limited.
  8. Click Save.

HaloPSA_1c.png

1d. Copy your Halo hostname

  1. Return to Configuration > Integrations > HaloPSA API.
  2. Under API Details, find the Resource Server value. It will look like https://yourcompany.halopsa.com/api, or https://yourcompany.haloitsm.com/api on HaloITSM.
  3. You need the hostname only: yourcompany.halopsa.com. Leave off the https:// prefix and the /api suffix.

HaloPSA_1d.png

1e. Check your Ticket Type for mandatory fields

Huntress sends a summary, a description, the Client, and the Ticket Type. It does not send Category, Impact, Urgency, or other custom fields.

If the Ticket Type you plan to use makes any of those fields mandatory with no default value, Halo will reject every Huntress ticket with a 400 error and no ticket will be created. This is the most common reason a test ticket is rejected outright.

Before you connect, open the Ticket Type you plan to use and, for each mandatory field that Huntress does not send, either clear the mandatory flag or set a default value.

If those fields must stay mandatory for your technicians, create a dedicated Huntress Ticket Type with the defaults configured, and select that Ticket Type in Step 3.

Step 2: Connect Huntress to Halo

  1. In the Huntress dashboard, go to Integrations and click Add.
  2. Under Notifications, select HaloPSA.
  3. On the Add HaloPSA Integration screen, enter:
    • Server Host: the hostname from step 1d, for example yourcompany.halopsa.com
    • Client ID: from step 1c
    • Client Secret: from step 1c
  4. Click Add.
Screenshot 2026-08-27 at 10.54.13 AM.png

Huntress authenticates against Halo. When authentication succeeds, the Authenticate setup step is marked complete and Huntress takes you to Select Defaults.

If the page keeps spinning and never advances, see Setup does not finish in Troubleshooting.

Step 3: Select your defaults

This is the second setup step. All three settings can be changed later.

  • Default Client: the Halo client Huntress uses when a Huntress organization has no explicit mapping. This is required.
  • Ticket Type: the Halo Ticket Type used for Huntress tickets. This is required. Use the Ticket Type you checked in step 1e.
  • Status after Huntress Resolution: the Halo status the ticket moves to when the Huntress notification is resolved. Leave this blank if you do not want Huntress to change ticket status.

Click Save Changes. Huntress takes you to the HaloPSA configuration page.

Screenshot 2026-08-27 at 10.55.17 AM.png

Step 4: Review mappings and options

The HaloPSA configuration page has three tabs. Map Organizations and Map Tickets are covered below. Billing sync is covered in a separate article. Click Save Changes when you are finished.

Map Organizations

  • Default Client: the client you chose in Step 3. You can change it here.
  • Organization Mappings: map each Huntress organization to a Halo client. Use Auto-map to match on name, then resolve anything left in the Unmapped list. Any organization you do not map will use the Default Client.

Map Tickets

  • Ticket Type and Status after Huntress Resolution: the values you chose in Step 3. You can change them here.
  • Notification Types: turn each notification type on or off, and optionally override the Ticket Type and resolution status for an individual type:
    • Incidents
    • Escalations
    • Platform Actions
    • Account Notices. These have no resolution status, because they are not resolved in Huntress.

Note: A per-type override takes precedence over the setting from Step 3. If you override a type, set its Ticket Type as well, because an override with no Ticket Type is not valid.

Step 5: Send a test ticket

  1. In the Huntress dashboard, go to Integrations.
  2. On the HaloPSA row, open the actions menu (the vertical dots) and select Send Test Ticket.
  3. Confirm the ticket appears in Halo, against the client you expect.

You can also select View PSA Tickets from the same menu to review the tickets Huntress has created.

If the test ticket fails, see Troubleshooting.

Troubleshooting

Setup does not finish and the page keeps spinning

Integration setup stays on a spinning indicator and never completes.

Solution

Check the following, in order:

  1. Server Host is the base Halo domain only, with no https:// prefix and no /api suffix.
  2. The application's Authentication Method is Client ID and Secret (Services).
  3. The application is enabled, and the Client ID and Client Secret were copied with no leading or trailing spaces.
  4. all is ticked on the application's Permissions tab.

If setup still fails, remove the HaloPSA integration in Huntress, add it again, and rerun the setup test.

Default Client shows "The results cannot be loaded"

The results cannot be loaded

Huntress authenticated, but the request to list Halo clients failed. Adding the integration only fetches a token, so reaching this screen does not prove the permissions are right.

Solution

  1. On the agent's Details tab, confirm the Huntress role is listed under Roles. Creating the role in step 1a does not attach it to the agent, and an agent with no role has no access to anything.
  2. On the Huntress role, confirm Customers Access Level is at least Read Only.
  3. On the API application's Permissions tab, confirm all is ticked, or read:customers if you granted individual scopes instead.
  4. Confirm Agent to log in as on the application points at the API-only agent from step 1b.

Application permissions are capped by the agent's role, so the scope, the role, and the role assignment all have to line up. This is why granting all on the application does not fix the error on its own.

Bad Request: "Please select a valid Client/Site/User"

Bad Request - "Please select a valid Client/Site/User"

Halo could not resolve a valid client, site, and user context for the ticket. Huntress sends the Client but does not send a specific user.

Solution

Create a General User at the top level in Halo (the MSP company level in HaloPSA), then send the test ticket again.

HTTP 401 or 403 during test ticket retrieval

the server responded with status 401 for GET [URL]

the server responded with status 403 for GET [URL]

Huntress created the ticket, but Halo rejected the request to read it back. This means the API-only agent can create tickets but cannot see them afterwards, usually because of team scope or ticket visibility restrictions.

Solution

Start with the agent's Departments & Teams tab. This is the usual cause and the step most often missed:

  • Under Teams, confirm the agent is a member of every team Huntress tickets could route to. If your teams changed after setup, the agent may have been dropped from one.
  • Set Membership level to all Departments to Modify All.

Then confirm:

  • The Huntress role is listed under Roles on the agent's Details tab, and grants Can view Unassigned Tickets and Can view Tickets that are assigned to other Agents.
  • The agent's Client Restrictions tab is empty, and no Ticket type restrictions are set.
  • If tickets route across multiple teams, the all:teams permission is granted on the API application.

Then run Send Test Ticket again. If the error persists, review the instance for non-standard team restrictions or assignment rules, and work with Halo Support as needed.

HTTP 400 during test ticket creation

the server responded with status 400, response_code: 400, response_body: "Category is mandatory\nImpact is mandatory\nUrgency is mandatory\n"

The Ticket Type Huntress is using enforces fields that Huntress does not send, so Halo rejects the request and no ticket is created. Field names vary by instance. The error names the specific fields blocking you.

Solution

  1. In Huntress, go to Integrations > HaloPSA > Map Tickets and note the Ticket Type. If the failing notification type has an override, note that Ticket Type instead.
  2. Open that Ticket Type in Halo and locate the fields named in the error. They may sit on the Ticket Type itself, or on its form or field group.
  3. For each field, either clear the mandatory flag or configure a default value so the ticket can be created through the API without user input.
  4. Save your changes, then run Send Test Ticket again in Huntress.

If those fields must stay mandatory for your normal workflows, use a dedicated Huntress Ticket Type with the defaults configured.

PSA ticket does not close when the Huntress notification is resolved

Resolved Huntress notifications are not closing the corresponding tickets in Halo.

Solution

Check the following, in order:

  1. In Huntress, go to Integrations > HaloPSA > Map Tickets and confirm Status after Huntress Resolution is set. If it is blank, Huntress intentionally leaves ticket status unchanged.
  2. If you set per-type overrides under Notification Types, confirm the relevant type also has a resolution status. A per-type override takes precedence over the global setting.
  3. Account Notices are not resolved in Huntress, so they never trigger a status change.
  4. On the agent's Departments & Teams tab, set Membership level to all Departments to Modify All. If it is on View All, Huntress can read the ticket but not change its status. This is the most common cause.
  5. If it still does not close, enable the all:teams permission on the API application, or Can Edit Tickets Which Are Not Assigned To Them on the agent.

If the ticket still does not close, the instance may have a workflow or status restriction blocking the transition. This is a non-standard setup and may require outreach to Halo Support.

Related articles