Prerequisites
- Administrator access to your Halo PSA instance
- Access to MSPortal.ai with integration management permissions
- (Recommended) Custom MSPortal role and API-only agent created in Halo PSA
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
- Click View Applications
- Create a new application named “MSPortal.ai”
- Select Client ID and Secret (Services) as the authentication method
- Save your Client ID and Client Secret - you’ll need these in the wizard
- Select your MSPortal API-only agent (see Create Custom Halo PSA Role and API User to set this up)
4
Configure Permissions
Click Permissions and configure the API permissions as shown in the table below.
Required API Permissions
Required API Permissions
| Permission | Enabled |
|---|---|
all | No |
all:standard | No |
admin | No |
all:teams | No |
admin:webhooks | No |
read:tickets | Yes |
edit:tickets | Yes |
read:calendar | Yes |
edit:calendar | Yes |
read:customers | Yes |
edit:customers | No |
read:crm | Yes |
edit:crm | Yes |
read:contracts | Yes |
edit:contracts | No |
read:suppliers | No |
edit:suppliers | No |
read:items | Yes |
edit:items | No |
read:projects | Yes |
edit:projects | Yes |
read:sales | Yes |
edit:sales | Yes |
read:quotes | Yes |
edit:quotes | No |
read:sos | No |
edit:sos | No |
read:pos | No |
edit:pos | No |
read:invoices | No |
edit:invoices | No |
read:reporting | No |
edit:reporting | No |
read:timesheets | No |
editMine:timesheets | No |
edit:timesheets | No |
read:softwarelicensing | Yes |
edit:softwarelicensing | No |
read:software | No |
edit:software | No |
read:kb | No |
edit:kb | No |
read:assets | No |
edit:assets | No |
read:distributionlists | No |
edit:distributionlists | No |
read:mailcampaign | No |
edit:mailcampaign | No |
access:chat | No |
access:adpasswordreset | No |
read:events | No |
edit:events | No |
5
Configure CORS Whitelist
- Click Security
- Add
app.msportal.aito the CORS whitelist - 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 4 easy steps.Starting the Wizard
1
Navigate to Integrations
In MSPortal.ai, go to Settings > Integrations.
2
Start Setup
Find the Halo 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:
| Field | Description |
|---|---|
| Halo URL | Your Halo PSA instance URL (e.g., https://yourhalo.halopsa.com) |
| Client ID | The Client ID from your Halo API application |
| Client Secret | The Client Secret from your Halo API application |
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 sync configuration.
Step 2: 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:
| Option | Description |
|---|---|
| Sync Users | Sync user/contact data from Halo PSA |
| Sync Companies | Sync company/client data from Halo PSA |
| Enable Ticket Sync | Sync tickets from Halo PSA |
| Enable Opportunity Sync | Sync opportunities from Halo PSA |
2
Configure Contact Auto-Import
If you want contacts to be automatically imported when companies are added:
- Enable Auto-Import to automatically create user accounts for active contacts
- Select a Default Role for Imported Contacts (e.g., Viewer)
3
Configure Ticket Sync Scope
Define which tickets to sync:
| Setting | Description |
|---|---|
| Teams to Sync | Select which Halo teams’ tickets to sync (only tickets from selected teams will appear in MSPortal) |
| Exclude Statuses | Select ticket statuses to exclude from sync (e.g., Closed, Cancelled) |
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.
4
Proceed
Click Next to continue to ticket and opportunity configuration.
Step 3: Configure
Set up ticket status mapping and opportunity defaults.Ticket Settings
1
Configure Status Settings
| Setting | Description |
|---|---|
| Closed Statuses | Select statuses that indicate a ticket is closed |
| Client Comment Status | Status to set when a client comments on a ticket (e.g., “Updated”) |
2
Configure Resolution Status Stepper
The Resolution Status Stepper provides a visual indicator of ticket progress. Map your Halo statuses to each stage:
| Stage | Description |
|---|---|
| New | Tickets that are newly created or not yet triaged |
| Triaged | Tickets that have been reviewed and categorized |
| Working | Tickets actively being worked on |
| Waiting | Tickets waiting for customer response or external input |
| Resolved | Tickets that have been completed |
3
Sync Actions
Use these buttons to manage ticket sync:
| Action | Description |
|---|---|
| Quick Sync | Trigger an immediate sync of ticket data |
| Clear & Resync | Delete all synced tickets and perform a fresh sync (useful after major configuration changes) |
Opportunity Settings
1
Configure Opportunity Defaults
Set default values for opportunities created from MSPortal:
| Setting | Description |
|---|---|
| Default Workflow | The Halo workflow to use for new opportunities |
| Default Conversion Probability | Starting probability percentage for new opportunities |
Opportunity sync can be enabled or disabled in the Sync step. These settings only apply when opportunity sync is enabled.
2
Proceed
Click Next to continue to the import step.
Step 4: 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 Users
- Import Companies
Import technicians and agents (your MSP staff) from Halo PSA to create user accounts.
- Enable Import Users Now
- Select users from the list to create accounts for
- 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
Troubleshooting
| Issue | Solution |
|---|---|
| Connection test fails | Verify your Halo URL, Client ID, and Client Secret are correct. Ensure app.msportal.ai is in the CORS whitelist. |
| Tickets not syncing | Check that the correct teams are selected in Ticket Sync Scope and that ticket statuses aren’t excluded. |
| Contacts not importing | Verify Auto-Import is enabled and a default role is selected in the Sync step. |
| Permission errors | Review the API permissions in Halo PSA and ensure all required permissions are enabled. |