Contact Mapping
How Voice AI Handles Contact Mapping
When a customer calls, Voice AI identifies who's calling and ensures the ticket is logged under the correct contact and company in your PSA (Professional Services Automation) system.
This article explains how the process works and how to troubleshoot contact mapping issues.
How Contact Mapping Works
Voice AI uses a two-layer process to identify callers: it first checks the phone number, and if that's not enough, it can use AI-powered name and company matching.
Layer 1: Phone Number Lookup
When a call comes in, Voice AI looks up the caller's phone number in your PSA.
- Single match found — The caller is identified immediately. No conversation is needed, and the ticket is assigned to that contact.
- No match found — The phone number isn't registered in your PSA. If AI caller identification is enabled, Voice AI moves to Layer 2 to identify the caller by name and company. Otherwise, the ticket is created under a default contact.
- Multiple contacts share the same number — Voice AI cannot determine which contact is calling from the phone number alone. If AI caller identification is enabled, it moves to Layer 2 and asks the caller for their name and company to find the right match. Otherwise, the ticket is created under a default contact.
- Match found but contact is inactive — The phone number belongs to a contact that has been deactivated in your PSA. Contact mapping fails. To fix this, reactivate the contact in your PSA and re-sync in Integrations.
- PSA data not yet synced — The contact and phone number may exist in your PSA, but Voice AI hasn't ingested them yet. This commonly happens if your PSA wasn't synced in Integrations before onboarding to Voice. To fix this, perform a re-sync in Settings → Integrations.
Layer 2: AI Identification (Name and Company Matching)
Requires: "Ask for caller's name and company" must be enabled under Attendant → Customize Agent behavior → AI caller identification in your agent settings. This setting is only available when using Advanced AI mode. Overflow inherits the AI caller identification settings from Advanced AI — if you only use Overflow, you'll still find this setting under the Attendant tab.
If the phone number doesn't find a verified match, Voice AI asks the caller for their name and company, then searches your PSA using accuracy scoring.
- Voice AI asks the caller for their name and company name.
- It searches the PSA for client companies that closely match the provided company name.
- It then searches within that company for contacts that match the caller's name.
- If a strong match is found for both the contact name and company name, Voice AI asks the caller to confirm:
- Confirmed (Overflow only) — the contact is assigned to the call.
- Denied — a default contact is assigned.
- If Voice AI can't find a confident match, a default contact is assigned. This can happen when:
- No contacts with a similar name exist in that company
- Multiple contacts have similar names, making it ambiguous
- The caller's name or company was misheard by speech recognition
- The company has a very large number of contacts
Voice AI makes one search attempt based on the name and company the caller provides. If it doesn't find a match, a default contact is assigned.
Note: Voice AI searches for contacts within a matched company only — it does not search across all contacts in your PSA.
Ticket Notifications for Unverified Callers
When Voice AI identifies a caller through AI (Layer 2) rather than by phone number, the ticket is flagged to let your team know the caller was not phone-verified:
- "Warning: User Not Authenticated" — appears on the ticket to indicate the caller's identity was not confirmed via phone number lookup.
This means Voice AI successfully identified the caller using their name and company, but because their phone number isn't registered in your PSA, the match is treated as unverified. The ticket note includes the caller's stated name and company for reference.
To resolve this: Add or update the caller's phone number in your PSA, then re-sync in Settings → Integrations. Future calls from that number will be verified automatically via Layer 1.
Failed Contact Mapping Notification
On the Voice dashboard, flagged calls show a warning icon with a tooltip so you can spot issues at a glance. Inside the call detail view, yellow notification banners explain exactly what happened:
- "This phone number isn't registered in your PSA"
- "Low confidence in company match" (caller's company may be abbreviated or hard to match)
- Contact is inactive in PSA
- PSA data not synced or request timed out
Each banner includes guidance on what to do next, so you can self-diagnose and correct the data in your PSA tool.
Known Limitations
Voice AI's contact matching has some known limitations to be aware of:
- Nicknames — Voice AI may not match common nicknames to formal names. For example, "Mike" may not match "Michael," and "Rob" may not match "Robert." If your contacts commonly go by nicknames, consider adding the nickname as an alternate name in your PSA.
- Company name variations — Differences in company name suffixes (e.g., "Inc" vs. "Corporation" vs. "LLC") or abbreviations can reduce matching accuracy.
- Large companies — Matching accuracy decreases as the number of contacts in a company grows. Companies with 50+ contacts may see noticeably lower match rates due to increased ambiguity.
- Partial names — Providing only a first name or only a last name reduces the chance of a successful match.
- Speech-to-text errors — Voice AI relies on speech recognition, which can mishear names — especially uncommon or non-English names. If a caller's name is consistently misheard, updating the PSA contact name to include a phonetic variation can help.
Troubleshooting Contact Mapping Issues
If Voice AI fails to correctly identify a contact, check the following:
Issue | What to do |
Phone number not found | Add or update the contact's phone number in your PSA, then re-sync in Integrations. |
Multiple contacts share the same phone number | Voice AI will ask the caller for their name and company. If this keeps causing issues, consider deduplicating phone numbers in your PSA so each number maps to a single contact, then re-sync. |
Contact is inactive | Reactivate the contact in your PSA and re-sync in Integrations. |
PSA data not synced | If you recently onboarded to Voice or made changes in your PSA, perform a re-sync in Settings → Integrations to ensure Voice AI has the latest data. |
Name or company not matched | The caller's name or company may have been misheard, or they may be using a nickname or abbreviation. Verify the contact's name and company are correct in your PSA, then re-sync. |
Persistent failures | If the issue continues after correcting PSA data and re-syncing, contact Thread Support. |
Tip: After making any changes to contacts or companies in your PSA, always re-sync your PSA data in Settings → Integrations to ensure Voice AI has the latest information.
FAQ
What happens if there's a spelling error in the caller's name or company? Voice AI uses fuzzy matching and can handle minor spelling differences. However, significant misspellings or very different name forms (like nicknames) may cause a match failure.
What if multiple contacts are found with similar names? Voice AI selects the best match based on the highest combined accuracy score for both name and company. If the score doesn't meet the confidence threshold, no match is made.
What if the contact Voice AI found isn't correct? Voice AI always asks the caller to confirm before assigning a contact. If the caller says it's incorrect, a default contact is assigned.
How many times will Voice AI try to find a match? Once. Voice AI searches based on the name and company the caller provides. If it doesn't find a match, a default contact is assigned and the call continues.
Can the caller change the contact after it's been confirmed? No. Once a contact has been confirmed, Voice AI does not allow reassignment during the call.
Does Voice AI search all contacts within the MSP? No. Voice AI first identifies the client company, then searches for a matching contact within that company only.
What happens if the caller's phone number matches an inactive contact? The match is not used. Voice AI treats inactive contacts as if they don't exist. Reactivate the contact in your PSA and re-sync to fix this.
What happens when multiple contacts share the same phone number? Voice AI can't tell who's calling from the phone number alone, so it will ask the caller for their name and company to find the right match. This adds a few seconds to the call. If you'd like to skip this step, ensure each phone number in your PSA is assigned to a single contact.
Can unverified callers update existing tickets?
No. Callers who are matched only by name and company (not verified by phone number) can only create new tickets. To update an existing ticket, the caller must be verified through Phone Number Lookup (Layer 1). To enable this, make sure the caller's phone number is registered in your PSA and synced in Integrations.
Can unverified callers update existing tickets? No. Callers who are matched only by name and company (not verified by phone number) can only create new tickets. To update an existing ticket, the caller must be verified through Phone Number Lookup (Layer 1). To enable this, make sure the caller's phone number is registered in your PSA and synced in Integrations.
