Skip to main content
This guide walks you through connecting your ConnectWise Manage instance to MSPortal.ai. Connecting an integration is an MSP staff task. Company users do not administer this connection. You set ConnectWise up first, then work through the tasks on the ConnectWise Manage connection page. See Connect and manage integrations for the tasks every connection shares.

Prerequisites

Before you begin, ensure you have:
  • Admin access to both ConnectWise Manage and MSPortal.ai
  • Your ConnectWise company ID (visible on the ConnectWise login screen)
  • Access to create API members and security roles in ConnectWise

Part 1: Configure ConnectWise Manage

Before connecting to MSPortal.ai, you need to create an API member and security role in ConnectWise.

Create Security Role

1

Access System Settings

Login to ConnectWise Manage and navigate to System > Security Roles.
2

Create Security Role

Create a security role named “MSPortal”. Expand each category and set the levels below. The names match the ConnectWise Security Roles screen. Leave every permission that is not listed, and every category not listed (such as Marketing), at None.Use All, not My: My limits the API member to records assigned to it, so syncs miss records and updates to other people’s work fail. A row marked only when is needed only if you use that feature; the rest of the integration works without it.
Project sync needs only Inquire on Project Headers and Project Tickets. The other levels are for creating and updating ConnectWise projects from MSPortal; see Project management permissions.
If Table Setup is customized to specific tables, allow at least General / Integrator Login for the ticket callback and Service / Service Board for boards.
Click Save and Close to finalize the security role settings.

Create API Member

1

Navigate to API Members

  1. Go to System > Members
  2. Click the API Members tab
  3. Click + to create a new API member
2

Configure API Member

  1. Name it “MSPortal”
  2. Select the MSPortal security role you created
  3. Enter your Business Unit and Location
  4. Click Save
3

Generate API Keys

  1. With the API member open, click the API Keys tab
  2. Click + to add a new key
  3. Name it “MSPortal” and click Save
  4. Important: Copy the Public Key and Private Key immediately
The API keys cannot be retrieved again after closing this dialog. Make sure to save them securely before proceeding.

Project management permissions

Skip this section unless you will create or update ConnectWise projects from MSPortal. The Project permissions in the role above already include these levels; use this section to check an existing role. The settings go on the role of the API member that owns the keys saved in MSPortal. Your staff member’s personal ConnectWise role does not give the integration any access.
1

Open the API member's role

In ConnectWise, go to System > Members > API Members, open the MSPortal API member and note its security role. Then open that role under System > Security Roles.
2

Set the Project permissions

Expand Project and set the levels below. Use All, not My, because My can stop the integration from updating work assigned to someone else.Project ticket status changes need Project Tickets > Edit Level: All. Project Ticket Tasks Edit only covers checklist changes.
3

Set the supporting permissions

Project management also uses records outside the Project module. Keep the required company, contact, member and lookup permissions, and set these for the features you use:These permissions do not override ConnectWise validation, board restrictions, closed record rules or required fields.
4

Decide on checklist deletion

Read, create and update work does not need Delete access, except removing someone from a project role, which needs Project Teams > Delete Level: All. To use Delete checklist item, also set Project > Project Ticket Tasks > Delete Level: All. Leave Delete off on other project records.
5

Save and re-check

Save the role. In MSPortal, open the ConnectWise Manage connection from Settings > Integrations, select Permissions and click Re-check.
MSPortal-only projects, portal templates and project registers use MSPortal permissions only. An explicit action that creates or updates a PSA project, phase or ticket needs the ConnectWise permissions above. ConnectWise access never grants a staff or client user access inside MSPortal.

What MSPortal writes back to ConnectWise projects

ConnectWise projects are two-way for status and dates. You do not need to repeat these changes in ConnectWise:
  • Project status, from the portfolio Kanban or the project’s status.
  • Project ticket status, from the project Board or ticket details.
  • Ticket owner, from the Resources board or the project Board.
  • Project, phase and ticket dates, from Reschedule, Edit dates, Projects > Dispatch, or ticket and phase details.
MSPortal writes to ConnectWise first and updates its own copy only after ConnectWise accepts the change. If ConnectWise rejects it, MSPortal shows an error and keeps the old value. Phase descriptions and notes, milestones, and project and onboarding templates stay in MSPortal. Onboarding task status syncs with ConnectWise, and an onboarding task due date changed in the portal is written to the linked ConnectWise ticket. Onboarding phase dates stay in MSPortal. See What writes back to your PSA.

Allow project checklist changes

Adding a checklist item or changing its completion writes to ConnectWise as the API member. The staff member needs the MSPortal project permission, and the API member separately needs ConnectWise access.
1

Find the API member

In ConnectWise, open System > Members > API Members and find the member that owns the public key saved in MSPortal.
2

Open its security role

Note the member’s security role, then open it under System > Security Roles.
3

Set Project Ticket Tasks

Expand Project and set Project Ticket Tasks:Keep the role dedicated to MSPortal. If another integration shares it, check the effect on that integration first.
4

Re-check in MSPortal

Save the role, then open the ConnectWise Manage connection from Settings > Integrations, select Permissions and click Re-check. Read the Project checklist writes result:
Projects and Project checklist writes are separate checks. With Project Ticket Tasks at Inquire All and Add/Edit None, staff can view checklists but cannot add items or change completion. Project sync keeps running while you fix the write permissions.

Part 2: Connect ConnectWise Manage in MSPortal

The ConnectWise Manage connection page lists its tasks in the Setup guide: Connect, Permissions, Choose data, Import or match companies, Import or match users, Import devices, Configure tickets, Configure opportunities and Review. Most tasks save each change as you make it, so you can leave and come back to any task later.

Connect

1

Open the connection page

In MSPortal.ai, go to Settings > Integrations. On the Directory tab, find ConnectWise Manage and click Connect. To continue an existing connection, open it from your active integrations instead.
2

Enter your API credentials

Fill in the following fields:
Site examples:
  • Cloud-hosted: na.myconnectwise.net, aus.myconnectwise.net, eu.myconnectwise.net
  • On-premise: cw.yourcompany.com (without https://)
3

Test the connection

Click Test connection and resolve any reported error. A successful test does not save the connection.If the connection fails:
  • Verify your site address is correct
  • Check that your Company ID matches exactly
  • Confirm the API keys are copied correctly
  • Ensure the API member has the correct security role assigned
4

Save

Click Save and continue to create the connection and move on to Permissions. For an existing connection, leave masked credentials unchanged to keep them, or enter replacements, test them and click Save changes.

Permissions

MSPortal checks which parts of ConnectWise your API member is allowed to read, and shows the result for each area of data. An existing Connected indicator is not proof of a fresh test.
1

Review the results

If the check has not run yet, click Run check. Each area of data is listed as granted, not permitted or could not verify.Areas under Required must be granted before you can continue: Companies, Contacts and staff, Tickets, and Boards and statuses. Without these the integration cannot function.Areas under Recommended cover Configurations, Opportunities, Product catalog, Invoices, Agreements, Projects, Project checklist writes, and Time entries.Importing project templates from ConnectWise into Settings > Projects > Templates also needs Project > Project Templates with Inquire Level: All. If the import dialog reports that ConnectWise refused the request, add that permission to the MSPortal security role and try again.
2

Grant anything missing

Any area that is not permitted shows the exact ConnectWise security role setting to change, for example Procurement -> Product Catalog (Inquire Level: All).Update the MSPortal security role in System > Security Roles, then come back and click Re-check.
Could not verify usually means ConnectWise was slow or unavailable, not that a permission is missing. Click Re-check before you change the role.
3

Reduce excess access

The check also reads the API member’s own security role and compares it with the MSPortal role in Create Security Role. If the role grants more, Permissions shows The ConnectWise Manage API user has more access than MSPortal needs and lists each permission set above that role, with the levels it grants and what MSPortal needs. For example, Companies -> Company Maintenance: Delete All. MSPortal needs Edit All, Inquire All. Any level on a permission the table does not list counts, including Inquire.MSPortal keeps working, but anyone who obtains the API keys gets the extra access. Go to System > Members > API Members, open the member that owns MSPortal’s API keys and note its security role. Lower each listed permission to what MSPortal needs under System > Security Roles. If the role is shared with people or other integrations, give the API member its own MSPortal role instead. Then click Re-check.The warning never blocks setup or turns off a sync.
4

Continue

You can continue with recommended areas ungranted. Those syncs stay switched off and their toggles are locked in Choose data until you grant the permission and re-check. Project checklist writes never turns off project sync.
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.

Choose data

Choose data lays its switches side by side in two groups, Core data and Extended data. Turning a dataset on reveals its settings below that group; turning it off hides them without clearing saved choices. Each switch and selector has an (i) beside its name: hover over, tap or focus it to read what the setting does. Each switch and selector saves when you change it. Wait for the saved state, and start the first sync when it is offered.
A toggle appears locked when the permission check found that your API member cannot read that data. Grant the permission named beside it in ConnectWise, then click Re-check on Permissions to unlock it.
Company & Data Sync Filters (under Sync Companies): Company Auto-Import: under Auto-Import Company Types, select the company types to create in the portal automatically during sync. MSPortal asks you to confirm before it imports a new batch, because companies are a billed item. Contact Auto-Import: turn on Contact Auto-Import to create user accounts for active contacts automatically when companies are added. Select a Default Role for Imported Contacts, and optionally use Add rule under Portal roles by contact type to give specific ConnectWise contact types other portal roles. Unmapped types use the default role.
We recommend choosing a role with minimal permissions if you plan to import all contacts.
Catchall contacts never sign in: ConnectWise files email from senders it cannot match under its built-in Catchall company. Those contacts can belong to any of your clients, so MSPortal ignores them: it never imports them as users, never links them to an existing user, and never lets anyone sign in to a user in the Catchall company. To give such a person access, move their contact to the right company in ConnectWise. After the next sync they import like any other contact, and a sign-in they already had moves to their new user automatically. To create portal users from your clients’ Microsoft 365 tenants instead, use an access rule with the action Import Microsoft 365 users (branch preview). See Set access rules. Planner auto-import: with Enable Opportunity Sync on, turn on Auto-import to Planner to create a planner item for each new ConnectWise opportunity. Use Minimum opportunity value and Opportunity types to auto-import to limit which ones come through. See Importing PSA Opportunities. Invoice visibility: with Enable Invoice Sync on, use Hide invoice statuses to choose the invoice statuses to hide from the Invoices page. Hiding a status does not stop those invoices from syncing. Ticket Sync Scope: with Enable Ticket Sync on, select the Boards to Sync and the statuses to exclude. Ticket Notes: company users see a ticket’s Discussion notes. Turn on Show resolution notes to company users to also show notes from the ConnectWise Resolution stream, for example when your technicians record the fix as a Resolution note. Internal Analysis notes are never shown to company users. The switch is off by default.
The first sync runs in the background and can take a few minutes, depending on the amount of data in your ConnectWise instance. Options in later tasks may be incomplete while it runs. Check errors and the connection’s sync result before treating an empty list as final.

Import or match companies

Open Import or match companies. Its first view, Import, includes unlinked records with or without suggestions; Suggested is available for reviewing proposed matches. Use the Import action beside a source company for a single import, or Import companies to open the selection dialog. The dialog loads unmatched records across provider pages for the current search. Use Select current page for its displayed page or Select all pages for every matching record. Review the names and selected count, then confirm the import. Existing portal companies with the same name are matched instead of duplicated. To link a company that already exists under a different name, choose it in the row, or review a suggested match and accept it. Review N suggested matches opens Accept suggested matches, which lists every suggestion at 70% confidence or more with those at 90% or more already selected. Lower the Auto-select by confidence slider, as far as 70%, to select weaker suggestions too, untick any pair you want to check yourself, then select Apply N Matches. Accepted matches, removed matches and ignores save when applied; opening the import dialog alone saves nothing.

Import or match users

Import or match at least one company, then open Import or match users for its contacts. You can leave other companies for later and return to import more users. The workspace opens on Import, which includes suggested contacts too.
  1. Use Import beside a contact, or select contacts and choose Import selected.
  2. Use the header checkbox to select the current page, click it again to select all pages matching the current filters, and click again to clear the selection. Use row checkboxes for individual contacts.
  3. Select all with email replaces the selection with contacts that have an email address across all pages matching the current filters.
  4. In the review panel, choose the Role and review the ready-to-import and skipped counts. Contacts without an email address are skipped; you can add an address before confirming. Correct invalid addresses or clear them to skip those contacts, and resolve duplicate addresses. Large selections are imported in batches.
To link an existing account, choose that user or accept a reviewed suggestion. Importing contacts does not invite them to the portal. See Import companies and Import users for selection scope and retry guidance.

Import devices

Import devices shows ConnectWise configurations. Match each ConnectWise configuration type to an MSPortal device type, turn on Auto-import for types you want imported on every sync, then import the staged configurations. Confirm the company and device type before importing, then check the result in Devices. See Import Devices for the full guide.

Configure tickets

Configure tickets sets ticket behavior inside MSPortal. Changes save as you make them. Wait for the saved state and resolve any reported save failure before you leave.
1

Review new ticket defaults

New ticket defaults sets the board and other PSA values used for new tickets created in the portal. These are the same defaults as Settings > Tickets, and editing them requires the Ticket Settings permission. It includes the Requester field, which records each submitter’s name in a ticket UDF. See Requester field.
2

Check which statuses count as closed

A ticket counts as closed when its ConnectWise status is marked Closed Status, or when the status’s SLA setting is Resolved. Statuses such as Completed usually stop the SLA clock before a later close, so their tickets leave the open ticket lists right away.If a board uses Resolved for a status that still means work is under way, such as Re-Opened, add it to Resolved statuses that stay open. Each name applies to every board you selected in Choose data, and a status marked Closed in ConnectWise always counts as closed.
3

Place statuses in resolution stages

The resolution stages drive the ticket progress indicator. Place each ConnectWise status in the stage it belongs to. A status can sit in one stage only.
4

Set the reply mailbox (optional)

Emailing ticket notes is off until you turn it on in Settings > Tickets > General > Email ticket notes. To let staff and company users email a ticket note on this connection, also set Reply mailbox under Emailing contacts from notes. Enter the mailbox ConnectWise reads incoming email from. MSPortal sends the note from your sending domain with this mailbox as the reply address and the ticket number in the subject, so a reply is added to the ticket. Without it, the Email to field is not offered on this connection’s tickets.
5

Sync tickets

See Clear and Resync Integrations before you use Clear & Resync.
Use Re-sync PSA Settings when newly created ConnectWise boards or statuses are missing.

Configure opportunities

Configure opportunities sets defaults for opportunities created from MSPortal and how synced opportunities update linked Planner items. Whether opportunities sync is chosen in Choose data.

Review and finish setup

Open Review and resolve any required incomplete tasks before selecting Finish setup. Each task saves its own changes; finishing setup does not apply a separate batch of pending company or user imports. Imports and syncs keep running in the background, so check their results.

Managing Your Integration

Open the connection from Settings > Integrations to manage it:
  • Overview and Sync activity show the connection’s health, matches and the outcome of each sync run.
  • Run sync in the connection header starts a sync for all data or for one dataset, such as tickets or PSA reference data.
  • Any setup task can be reopened from the Setup guide to change its settings.
On the ConnectWise Manage row in Settings > Integrations, the row’s More actions menu also offers:
  • Sync PSA data: Refresh configuration data (priorities, boards, statuses, types) from ConnectWise. See Re-sync PSA Settings.
  • Import configurations: Open the Import devices task, where you map ConnectWise configuration types to MSPortal device types, turn on auto-import, and ignore records you don’t need. See Import Devices.
To remove the integration, open More actions in the connection header and choose Disconnect…. Review the confirmation: disconnecting removes the stored credentials, company matches and data synced from this connection, and cannot be undone. Disconnecting does not revoke the API keys in ConnectWise; delete them there separately.

Devices from ConnectWise configurations

MSPortal treats an RMM, MDM or network tool as the source of truth for a device. When an RMM is connected, a ConnectWise configuration keeps or creates a device only when its type has Auto-import on and is not ignored in Import Devices. Configurations of other types add their details to devices your RMM reports.
  • Configurations removed in ConnectWise. Once a day MSPortal checks the full list of active configurations in ConnectWise. A configuration that is deleted or made inactive is removed from staging three days after ConnectWise stops listing it, and stays if it comes back in the meantime.
  • What happens to the device. When the configuration leaves staging, its device moves to another integration that still reports it, such as your RMM. A device nothing else reports is removed. In a tenant with an RMM, an IT Glue or other PSA record keeps the device only when its type has Auto-import on.
Only companies still mapped to this connection are affected. Unmapping a company or excluding a type stops syncing those records and keeps their devices. Archived devices are never removed.

Troubleshooting

Frequently asked questions

No. Select Save and continue after a successful test to create a connection, or Save changes to save replacement credentials on an existing connection.
Not every write. Sync checks probe read access, while Project checklist writes reads the API member’s task permission levels without changing data. Creating tickets, comments or other ConnectWise changes still needs the relevant write permission and a successful action.
It writes back. Project status, ticket status, ticket owners, and project, phase and ticket dates you change in MSPortal are written to ConnectWise, so you do not update them again there. Milestones and onboarding portal dates stay in MSPortal. See What MSPortal writes back to ConnectWise projects.
No. Check the background sync result and verify company, user and device imports separately.
No. Discovery and import are separate. Review user matches, company links and the permissions assigned to portal users; invitation is a separate workflow.
A retest only verifies access. Select Save changes after testing the replacement credentials, then confirm the saved connection before revoking the old keys in ConnectWise.