> ## 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.

# Configure Halo PSA Integration

> Connect your Halo PSA instance to MSPortal.ai using the step-by-step setup wizard

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

## Prerequisites

* Administrator access to your Halo PSA instance
* Access to MSPortal.ai with integration management permissions
* (Recommended) [Custom MSPortal role and API-only agent](/user-guides/integrations/halo-psa-custom-role-and-user) created in Halo PSA

## Part 1: Configure Halo PSA

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

<Steps>
  <Step title="Log in to Halo PSA">
    Navigate to your Halo PSA instance and log in with an administrator account.
  </Step>

  <Step title="Open Integrations">
    Click **Configuration** in the navigation menu, then select **Integrations** > **API**.
  </Step>

  <Step title="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](/user-guides/integrations/halo-psa-custom-role-and-user) to set this up)

    <Warning>
      Make sure to save your Client ID and Client Secret immediately. The secret cannot be retrieved after creation.
    </Warning>
  </Step>

  <Step title="Configure Permissions">
    Click **Permissions** and configure the API permissions as shown in the table below.

    <Accordion title="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`          | **Yes** |
      | `edit:invoices`          | **Yes** |
      | `read:reporting`         | No      |
      | `edit:reporting`         | No      |
      | `read:timesheets`        | **Yes** |
      | `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`            | **Yes** |
      | `edit:assets`            | **Yes** |
      | `read:distributionlists` | No      |
      | `edit:distributionlists` | No      |
      | `read:mailcampaign`      | No      |
      | `edit:mailcampaign`      | No      |
      | `access:chat`            | No      |
      | `access:adpasswordreset` | No      |
      | `read:events`            | No      |
      | `edit:events`            | No      |
    </Accordion>
  </Step>

  <Step title="Configure CORS Whitelist">
    1. Click **Security**
    2. Add `app.msportal.ai` to the CORS whitelist
    3. Click **Submit** to save
  </Step>
</Steps>

***

## 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

<Steps>
  <Step title="Navigate to Integrations">
    In MSPortal.ai, go to **Settings** > **Integrations**.
  </Step>

  <Step title="Start Setup">
    Find the **Halo** integration card and click **Configure** to launch the setup wizard.
  </Step>
</Steps>

***

### Step 1: Connect

Enter your Halo PSA API credentials to establish the connection.

<Steps>
  <Step title="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                  |
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify your credentials. You'll see a green "Connected" status when successful.

    <Note>
      If the connection fails, double-check your credentials and ensure the CORS whitelist includes `app.msportal.ai`.
    </Note>
  </Step>

  <Step title="Proceed">
    Once connected, click **Next** to continue to sync configuration.
  </Step>
</Steps>

***

### Step 2: Sync

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

<Steps>
  <Step title="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       |
  </Step>

  <Step title="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)

    <Tip>
      All auto-imported contacts will be assigned the selected role. You can change individual user roles later in Settings > Users.
    </Tip>
  </Step>

  <Step title="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)                               |

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to ticket and opportunity configuration.
  </Step>
</Steps>

***

### Step 3: Configure

Set up ticket status mapping and opportunity defaults.

#### Ticket Settings

<Steps>
  <Step title="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") |
  </Step>

  <Step title="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                        |

    <Tip>
      You can map multiple Halo statuses to each stage. The stepper will show the appropriate stage based on the ticket's current status.
    </Tip>
  </Step>

  <Step title="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) |
  </Step>
</Steps>

#### Opportunity Settings

<Steps>
  <Step title="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.

    | Setting                            | Description                                                                                                |
    | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
    | **Default Workflow**               | The Halo workflow new opportunities are placed into                                                        |
    | **Default Stage**                  | The starting stage within the chosen workflow                                                              |
    | **Default Type**                   | Halo opportunity type assigned to new opportunities                                                        |
    | **Default Conversion Probability** | Starting probability percentage                                                                            |
    | **Categories 1 - 4**               | Halo's four required category fields, each picked from a native dropdown populated from your Halo instance |

    <Tip>
      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.
    </Tip>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to the import step.
  </Step>
</Steps>

#### 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:

| Setting                              | Description                                                                                                                                                                                                                |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable opportunity auto-import**   | Master toggle. When off, opportunities only come into the planner via the manual Import Opportunities dialog                                                                                                               |
| **Minimum value**                    | Skip opportunities below a dollar threshold (useful for filtering out noise from small stub deals)                                                                                                                         |
| **Opportunity types to auto-import** | Multi-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](/user-guides/planner/index#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.

<Tabs>
  <Tab title="Import Users">
    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

    <Note>
      Client contacts are not imported here. They can be managed via Company settings after companies are imported.
    </Note>
  </Tab>

  <Tab title="Import Companies">
    Import companies from Halo PSA to sync their data.

    1. Enable **Import Companies Now**
    2. Select companies to import or link to existing MSPortal companies

    <Tip>
      Companies will sync automatically based on your sync settings. Use this option if you want to import specific companies immediately.
    </Tip>
  </Tab>
</Tabs>

***

### Complete Setup

Click **Complete Setup** to finish the wizard. Your Halo PSA integration is now configured!

<Note>
  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.
</Note>

***

## 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](/user-guides/integrations/import-devices) for the full guide.

## 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.                            |