Skip to main content
This guide walks you through connecting your Halo PSA instance to MSPortal.ai using our streamlined setup wizard.

​
Prerequisites

​
Part 1: Configure Halo PSA

Before connecting to MSPortal.ai, you need to create an API application in Halo PSA.
1

Log in to Halo PSA

Navigate to your Halo PSA instance and log in with an administrator account.
2

Open Integrations

Click Configuration in the navigation menu, then select Integrations > API.
3

Create API Application

  1. Click View Applications
  2. Create a new application named “MSPortal.ai”
  3. Select Client ID and Secret (Services) as the authentication method
  4. Save your Client ID and Client Secret - you’ll need these in the wizard
  5. Select your MSPortal API-only agent (see Create Custom Halo PSA Role and API User to set this up)
Make sure to save your Client ID and Client Secret immediately. The secret cannot be retrieved after creation.
4

Configure Permissions

Click Permissions and configure the API permissions as shown in the table below.
5

Configure CORS Whitelist

  1. Click Security
  2. Add app.msportal.ai to the CORS whitelist
  3. Click Submit to save

​
Part 2: MSPortal Setup Wizard

MSPortal.ai provides a guided setup wizard that walks you through connecting and configuring your Halo PSA integration in 5 easy steps.

​
Starting the Wizard

1

Navigate to Integrations

In MSPortal.ai, go to Settings > Integrations.
2

Start Setup

Find the Halo PSA integration card and click Configure to launch the setup wizard.

​
Step 1: Connect

Enter your Halo PSA API credentials to establish the connection.
1

Enter API Credentials

Fill in the following fields:
2

Test Connection

Click Test Connection to verify your credentials. You’ll see a green “Connected” status when successful.
If the connection fails, double-check your credentials and ensure the CORS whitelist includes app.msportal.ai.
3

Proceed

Once connected, click Next to continue to the permission check.

​
Step 2: Permissions

MSPortal checks what your Halo API application is allowed to read, and shows the result for each area of data.
1

Review the results

The check runs automatically when you reach this step. Each area of data is listed as either granted or unavailable.Areas marked Required must be granted before you can continue: Companies, Contacts and staff, Tickets, and Boards and statuses (statuses, priorities and ticket types). Without these the integration cannot function.Optional areas cover Assets, Opportunities, Product catalog, Invoices, Contracts, Projects, and Time entries.
2

Grant anything missing

Any area that is not permitted shows the exact Halo permission to grant, for example read:items for the product catalog.Open your MSPortal application under Configuration > Integrations > API > Applications, grant the permission (or the all scope), then come back and click Re-check.
Halo often refuses a scope-limited application at the token endpoint rather than per resource. If every area comes back unchecked with an authentication error, widen the application’s permissions rather than chasing individual areas.
3

Continue

You can continue with optional areas ungranted. Those syncs stay switched off and their toggles are locked on the next step until you grant the permission and re-check.
If a permission is removed later, MSPortal switches off the affected sync and notifies your integration admins rather than retrying against an endpoint it can no longer read.

​
Step 3: Sync

Configure what data to sync from Halo PSA and set up automatic contact import.
1

Configure Data Sync Options

Enable or disable the following sync options:
2

Configure Contact Auto-Import

If you want contacts to be automatically imported when companies are added:
  1. Enable Auto-Import to automatically create user accounts for active contacts
  2. Select a Default Role for Imported Contacts (e.g., Viewer)
All auto-imported contacts will be assigned the selected role. You can change individual user roles later in Settings > Users.
3

Configure Ticket Sync Scope

Define which tickets to sync:
When you proceed to the next step, data sync will begin in the background. This may take a few minutes depending on the amount of data in your Halo PSA account.Syncs are automatically deduplicated - if you navigate back and forth between steps, the same sync will not run multiple times within a 2-minute window.
4

Proceed

Click Next to continue to ticket and opportunity configuration.

​
Step 4: Configure

Set up ticket status mapping and opportunity defaults.

​
Ticket Settings

1

Configure Status Settings

2

Configure Resolution Status Stepper

The Resolution Status Stepper provides a visual indicator of ticket progress. Map your Halo statuses to each stage:
You can map multiple Halo statuses to each stage. The stepper will show the appropriate stage based on the ticket’s current status.
3

Sync Actions

Use these buttons to manage ticket sync:

​
Opportunity Settings

1

Configure Opportunity Defaults

Set default values for opportunities created from MSPortal. Halo requires several fields on every opportunity, so configuring defaults here means the planner Create Opportunity action can post a complete opportunity to Halo without prompting for them every time.
All six pickers read directly from your Halo instance, so the values you see are the same ones a Halo agent would see in the native UI. Any new workflow, stage, type, or category you add in Halo appears here on the next sync.
Opportunity sync can be enabled or disabled in the Sync step. These settings only apply when opportunity sync is enabled. When the planner posts a new opportunity, real Halo errors (missing Category 4, validation failures, etc.) now surface in the planner UI instead of failing silently, so misconfigured defaults are easy to spot.
2

Proceed

Click Next to continue to the import step.

​
Auto-Import Opportunities (Optional)

If you want Halo opportunities to auto-create planner items as new ones land in Halo, enable opportunity auto-import on the Opportunity Settings card. Two related controls scope which opportunities flow through: Once enabled, every Halo sync auto-creates planner items for new matching opportunities and keeps existing PSA-managed planner items in sync (title, description, due date, estimated value). See Importing PSA Opportunities in the Planner guide for the full sync behavior.

​
Step 5: Import (Optional)

Import users and companies from Halo PSA. This step is optional - you can skip it and import later from the respective settings pages.
Import technicians and agents (your MSP staff) from Halo PSA to create user accounts.
  1. Enable Import Users Now
  2. Select users from the list to create accounts for
  3. Choose a default role for imported users
Client contacts are not imported here. They can be managed via Company settings after companies are imported.

​
Complete Setup

Click Complete Setup to finish the wizard. Your Halo PSA integration is now configured!
You can return to the setup wizard at any time by clicking Configure on the Halo integration card. The wizard will resume with your current settings.

​
Managing Your Integration

After setup, you can manage your integration from Settings > Integrations:
  • Configure: Re-open the setup wizard to modify settings
  • Resync: Trigger a manual sync of data
  • Sync PSA Data: Refresh configuration data from Halo PSA

​
Additional Features

Once your integration is configured, MSPortal.ai will sync data from Halo PSA. You can:
  • View synced tickets in the Tickets module
  • Access customer data in the Companies module
  • Create opportunities from the Planner module
  • Link projects to planner items
  • Import Assets: Navigate to the Assets tab on your Halo integration to import hardware assets. Map Halo asset types to MSPortal device types, enable auto-sync, and ignore categories you don’t need. See Import Devices for the full guide.

​
Troubleshooting