Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.msportal.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
PermissionEnabled
allNo
all:standardNo
adminNo
all:teamsNo
admin:webhooksNo
read:ticketsYes
edit:ticketsYes
read:calendarYes
edit:calendarYes
read:customersYes
edit:customersNo
read:crmYes
edit:crmYes
read:contractsYes
edit:contractsNo
read:suppliersNo
edit:suppliersNo
read:itemsYes
edit:itemsNo
read:projectsYes
edit:projectsYes
read:salesYes
edit:salesYes
read:quotesYes
edit:quotesNo
read:sosNo
edit:sosNo
read:posNo
edit:posNo
read:invoicesYes
edit:invoicesYes
read:reportingNo
edit:reportingNo
read:timesheetsYes
editMine:timesheetsNo
edit:timesheetsNo
read:softwarelicensingYes
edit:softwarelicensingNo
read:softwareNo
edit:softwareNo
read:kbNo
edit:kbNo
read:assetsYes
edit:assetsYes
read:distributionlistsNo
edit:distributionlistsNo
read:mailcampaignNo
edit:mailcampaignNo
access:chatNo
access:adpasswordresetNo
read:eventsNo
edit:eventsNo
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 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:
FieldDescription
Halo URLYour Halo PSA instance URL (e.g., https://yourhalo.halopsa.com)
Client IDThe Client ID from your Halo API application
Client SecretThe 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:
OptionDescription
Sync UsersSync user/contact data from Halo PSA
Sync CompaniesSync company/client data from Halo PSA
Enable Ticket SyncSync tickets from Halo PSA
Enable Opportunity SyncSync opportunities from Halo PSA
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:
SettingDescription
Teams to SyncSelect which Halo teams’ tickets to sync (only tickets from selected teams will appear in MSPortal)
Exclude StatusesSelect 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.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 3: Configure

Set up ticket status mapping and opportunity defaults.

​
Ticket Settings

1

Configure Status Settings

SettingDescription
Closed StatusesSelect statuses that indicate a ticket is closed
Client Comment StatusStatus 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:
StageDescription
NewTickets that are newly created or not yet triaged
TriagedTickets that have been reviewed and categorized
WorkingTickets actively being worked on
WaitingTickets waiting for customer response or external input
ResolvedTickets that have been completed
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:
ActionDescription
Quick SyncTrigger an immediate sync of ticket data
Clear & ResyncDelete 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. 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.
SettingDescription
Default WorkflowThe Halo workflow new opportunities are placed into
Default StageThe starting stage within the chosen workflow
Default TypeHalo opportunity type assigned to new opportunities
Default Conversion ProbabilityStarting probability percentage
Categories 1 - 4Halo’s four required category fields, each picked from a native dropdown populated from your Halo instance
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:
SettingDescription
Enable opportunity auto-importMaster toggle. When off, opportunities only come into the planner via the manual Import Opportunities dialog
Minimum valueSkip opportunities below a dollar threshold (useful for filtering out noise from small stub deals)
Opportunity types to auto-importMulti-select list of Halo opportunity types. The picker is populated from the distinct opp_type values that have actually appeared in your Halo data, since Halo’s opptype is free-text rather than a managed picklist
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 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 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

IssueSolution
Connection test failsVerify your Halo URL, Client ID, and Client Secret are correct. Ensure app.msportal.ai is in the CORS whitelist.
Tickets not syncingCheck that the correct teams are selected in Ticket Sync Scope and that ticket statuses aren’t excluded.
Contacts not importingVerify Auto-Import is enabled and a default role is selected in the Sync step.
Permission errorsReview the API permissions in Halo PSA and ensure all required permissions are enabled.