Account Mapping
How to tell Gradient which vendor accounts belong to which customers in your PSA, and why getting this right is the foundation of everything.
Table of Contents
- How Auto-Mapping Works
- How to Map Accounts
- Should I Map or Exclude?
- The Goal: Zero Unmapped
- Monthly Maintenance
- PSA-Specific Gotchas
- Flagging Special Accounts with Tags
- Troubleshooting
What is Account Mapping?
When you connect a vendor integration, Gradient pulls in a list of all the companies from that vendor's portal. Account Mapping is simply the process of telling Gradient which of those vendor companies matches which customer in your PSA.
Without this step, Gradient can't compare vendor usage against your PSA agreements, it doesn't know that "ABC Engineering" in Huntress is the same customer as "ABC Engineering, Inc." in ConnectWise. Once you've mapped an account, Gradient knows exactly where to look, and reconciliation starts working.
Heads up on terminology: Different PSAs use different names for the same concept. What Gradient calls an "Account" is known as a Company in ConnectWise, an Account in Autotask, and a Customer in HaloPSA and Syncro. For a full reference, see the PSA Naming Conventions article.
How Auto-Mapping Works
Gradient will automatically map a vendor account to a PSA account when the names are an exact, character-for-character match. Capitalization, spacing, punctuation, it all has to be identical.
This means:
- "Acme Corp" in Huntress + "Acme Corp" in your PSA = auto-mapped
- "Acme Corp" in Huntress + "Acme Corporation" in your PSA = unmapped, needs manual mapping
- "Acme Corp" in Huntress + "acme corp" in your PSA = unmapped, needs manual mapping
Any account that doesn't auto-map will appear with an Unmapped status. These are the ones that need your attention.
Why doesn't Gradient do fuzzy matching? Because guessing wrong is worse than not guessing at all. If Gradient auto-mapped "Acme Corp" to "Acme Capital" by mistake, you'd be comparing the wrong vendor data against the wrong agreements, and you might not catch it for months. Exact matching keeps things safe and auditable.
How to Map Accounts
Account mapping happens in two places: during the integration setup wizard, and in Advanced Config afterwards. Both lead to the same result.
During the integration setup wizard
When you connect a new integration, Gradient walks you through account mapping as part of the setup flow. You'll see a list with the vendor account names on the left and a dropdown on the right to select the matching PSA account.
- For accounts that have been auto-mapped, you'll see the PSA match already selected. Give these a quick sanity check to confirm they look right.
- For Unmapped accounts, click into the right-hand dropdown and start typing, two characters is usually enough to bring up the right match.
- Use the pin icon (funnel icon) to the right of each row to auto-fill the first word of the vendor account name into the search, which can speed things up considerably.
- You don't need to map every account before hitting Next. Map what you can, then come back later via Advanced Config to finish the rest.
After setup, via Advanced Config
Advanced Config is the best place to finish mapping and do your ongoing monthly maintenance. It shows all your integrations in one view so you're not jumping between individual vendor setup screens.
- From the left-hand navigation, select Data Sources > Advanced Config.
- You'll land on the Account Mapping tab by default.
- Use the filter at the top of the Integration column to focus on one vendor at a time if needed.
- Click the Unmapped filter button to show only the accounts that still need attention.
- For each unmapped row, click the PSA dropdown on the right and search for the correct customer.
Top
Should I Map or Exclude?
Every account in Gradient needs to be in one of three states: Mapped, Excluded, or Unmapped. The goal is to have nothing sitting in Unmapped, because Unmapped means Gradient can't do anything useful with it.
Here's how to decide what to do with each account:
|
Situation |
What to do |
Why |
|
The customer exists in your PSA |
Map it |
Even if they're a former customer, mapping means Gradient will surface any usage that's still running under their account, which is exactly the kind of thing you want to catch. |
|
The customer exists in the vendor portal but has been fully removed from your PSA (no account record at all) |
Exclude it |
There's nothing to map to, so excluding clears it from your to-do list and tells Gradient you've made a conscious decision about it. |
|
An internal account, sandbox, or test company you don't bill |
Exclude it |
Keeps your reconciliation view clean and focused on real billing relationships. |
|
A vendor account that maps to multiple PSA companies (e.g., a parent account with multiple sites) |
Map to the main/parent record and add a note or tag |
Account mapping is one-to-one. Map to the primary PSA record, then use Tags to flag it for manual review each month. |
Resist the urge to exclude former customers if they still have a PSA record. The whole point of Gradient is catching things that slipped through the cracks. A former client with a device still sitting in Huntress is exactly what you want to find, not hide.
The Goal: Zero Unmapped
The unmapped count at the top of the Account Mapping screen in Advanced Config is your early-warning system. When it reads zero, you know Gradient has a clear answer for every vendor account it can see, either it's mapped to a PSA customer, or you've deliberately excluded it.
When it's not zero, something needs your attention. Either:
- A new customer was added to a vendor portal and Gradient found them but doesn't know who they are in your PSA yet, or
- An existing account was renamed in the vendor portal, breaking the previous mapping.
Either way, that Unmapped count is a signal worth acting on. Leaving accounts unmapped means Gradient won't show you reconciliation data for those customers, so you're flying blind on their usage.
Make it a habit: The first thing to do at the start of every monthly reconciliation is open Advanced Config and check that your unmapped count is still zero. It only takes a few seconds and it means you're working with complete data when you get to Contract Reconciliation.
Monthly Maintenance
Account mapping isn't a one-and-done task. A few things can cause previously mapped accounts to drift back to Unmapped over time:
When a client gets renamed
Mapping is based on name. If someone renames an account in the vendor portal, even just a capitalization change or punctuation tweak, that account will appear as Unmapped because Gradient can no longer find the name it was looking for. The fix is a quick remap in Advanced Config.
When a new customer is added to a vendor portal
Any time a tech provisions a new customer in a vendor portal, that company will appear as Unmapped in Gradient until you tell it which PSA customer it belongs to. This is one of the most common reasons the unmapped count goes up between billing cycles.
When you connect a new integration
Every time you add a new vendor integration, you'll have a fresh batch of accounts to map. The setup wizard handles the obvious ones, but there will almost always be some left to finish in Advanced Config afterwards.
After making changes in your PSA: If you've renamed a customer, changed their status, or made other PSA-side changes, run a full PSA sync before heading into Advanced Config. This ensures Gradient's account list reflects the current state of your PSA. You can trigger a full sync from Settings > Data Settings > PSA Configuration > Start Full Sync.
PSA-Specific Gotchas
A few things in your PSA can cause accounts to not show up in Gradient even after a successful sync. Here are the most common ones.
ConnectWise: Companies tagged as "Vendor"
Gradient deliberately skips any ConnectWise company that has the Vendor type tag applied. This is usually the right behaviour, you don't want to reconcile usage for your vendors. But if you have a company that is both a vendor and a client (for example, a cabling company you also sell managed services to), that company will be invisible to Gradient until the Vendor tag is removed or a separate client record is created for them.
The fix: remove the Vendor tag from the company in ConnectWise, then run a full PSA sync. The company will appear in Gradient's account mapping list on the next sync.
ConnectWise and other PSAs: Prospects not showing up
If a customer is still set to a Prospect status in your PSA rather than an active client status, Gradient may not surface them. If you've started provisioning services for a new client but haven't converted them from prospect to client in your PSA yet, you won't be able to map their vendor accounts in Gradient until that status is updated.
The fix: update the company status in your PSA, then run a full PSA sync.
General: Changes in your PSA aren't reflected yet
Gradient syncs your PSA on a schedule, so recent changes (new companies, renames, status changes) won't show up immediately. If you've just made a change and need it to appear now, run a manual full PSA sync from Settings > Data Settings > PSA Configuration > Start Full Sync.
Flagging Special Accounts with Tags
Some accounts don't fit cleanly into a one-to-one mapping, maybe it's a client with multiple agreements split across departments, or a parent account with several subsidiary sites. Gradient's account mapping is one-to-one, so you'll map to the primary PSA record, but you can use Tags to make sure these accounts get the right attention each month.
A tag like "Manually Reconcile" or "Multi-Site" on an account is visible right on the Contract Reconciliation dashboard, so anyone doing the monthly reconciliation knows to handle that customer differently without having to remember it from scratch every time.
Tags live on the dashboard under each account name. Select the tag icon to create and apply them. For full details, see the Notes and Tags article.
Troubleshooting
A customer I know exists isn't showing up in the mapping dropdown
Try these in order:
- Run a full PSA sync and wait for it to complete, then try again.
- In ConnectWise, check whether the company has the Vendor tag applied. If so, remove it and sync again.
- Check the company's status in your PSA. If it's set to Prospect or Inactive, update it to an active client status and sync again.
- Check your ConnectWise API security level settings to confirm the agreement type isn't restricted from syncing to Gradient.
An account I mapped before is now showing as Unmapped
The most common cause is a name change, either in the vendor portal or in your PSA. Gradient looks for an exact name match, so if either side changed, the mapping breaks. Find the account in Advanced Config, check what the vendor is now calling it, and remap it to the correct PSA customer.
My unmapped count keeps going back up after I clear it
This usually means new customers are being added to vendor portals without the corresponding account mapping being updated in Gradient. The fix is procedural: make "check unmapped count" the first step of your monthly reconciliation process. Some teams also add it to their new client onboarding checklist so that whenever a new customer is provisioned in a vendor portal, someone updates the mapping in Gradient at the same time.
I accidentally excluded an account and need to bring it back
No problem, nothing in Gradient's account mapping is permanent. Go to Data Sources > Advanced Config > Account Mapping, find the excluded account, and change its status back to Mapped (or Unmapped if you want to remap it fresh). All changes here are fully reversible.
Still stuck? Reach out at support@meetgradient.com and we'll get you sorted. 🦩