When verifying contact data at scale, knowing which person is linked to which phone number is crucial. In many cases, a phone number might return a positive name match because the input name appears somewhere in the identity record (perhaps tied to a family mobile plan or shared by a household), but that person is a secondary associate rather than the primary owner.
Name Match Details provides granular insights beyond a simple true/false match we have today in our Real Contact API, allowing you to distinguish between primary owner and associated names. This feature is available within our Real Contact API for enterprise customers who need help assuring they’re reaching the right individual.
What are Name Match Details? #
Standard Name Match logic often returns a “True” match if the input name exists anywhere in the identity record for that phone number. For companies validating contacts at scale (whether cleansing internal databases, verifying leads before handoff, or confirming decision-maker identity) “close” isn’t always good enough.
Example Scenario:
- Input Name: John Smith
- Record: The phone is on a plan owned by Jane Smith (spouse), but John Smith is listed as an associate.
- Standard RC 2.0 response: Returns “name_match”: true
- With Name Match Details: You can identify if John Smith is the best name (primary owner) or simply a match found within the record.
What are the benefits of Name Match Details? #
- Reach the right person, not just a ‘matching’ name: Standard name matching only tells you if a name exists somewhere in the record. Name Match Details confirms whether you’re reaching the primary owner or a secondary associate, so you’re not wasting time on contacts that technically “match” but aren’t who you need.
- Higher-quality lead handoffs: Sales teams get contacts that have been verified down to ownership level. Instead of passing along names that happen to appear on a shared phone plan, you can confirm the contact you’re handing off is actually the decision-maker.
- Stronger compliance confidence: For TCPA-adjacent workflows and consent verification, having a better idea of who you’re contacting adds a layer of defensibility to your outreach.
- Cleaner data at scale: When you’re validating thousands of records, Name Match Details lets you programmatically filter for primary owner vs. associates. This keeps your CRM and outreach lists focused on high-quality contacts.
- Built-in data quality signal: The confidence score (50-90) tells you how strong the phone-to-name association is in our records, even when name_match is false. Use it to understand when a non-match is due to weak data vs. a genuine mismatch.
- Complements IP intelligence: Name Match Details pairs with IP-based intelligence signals (trust_score and ip_distance_to_address) to provide a fuller picture of the legitimacy of the interaction and identity alignment.
How do I interpret each field? #
Name Match Details is a nested object (name_match_details) returned within the Real Contact 2.0 API response. It contains three key fields:
1. match_type
This indicates the granularity of name matching: whether it’s an exact match, a partial match, or no match was found.
| Response | Description | Example (Input : Record) |
| Exact Name Match | Full name matches including synonyms, initials, and normalized variations. | “John Smith” : “Jonathan Smith”“J Smith” : “John Smith”“SMITH John” : “jonathan s” |
| First Name Match | Only the first name matches; the last name does not. | “John Wayne” : “John Smith” |
| Last Name Match | Only the last name matches; the first name does not. | “Joseph Smith” : “John Smith” |
| null | No name match was found. | “Alan Moore” : “John Smith” |
2. is_best_name
This boolean field indicates whether the input name is considered the primary owner (highest ownership rank) of the phone number.
- True: The input name is the most likely owner.
- False: The input name is an associate or secondary user, even if name_match is True.
3. confidence_score
A numerical value ranging from 50 to 90 that indicates the strength of the link between the name and the phone number. A higher confidence score indicates a stronger phone-to-name association.
| Score | Confidence Level |
| 70+ | High confidence |
| 60 | Medium confidence |
| 50 | Insufficient data |
Note: This score reflects confidence in our data record, not the input. A confidence score is always returned, even when phone.name_match is False. This is useful for understanding data quality on non-matches.
API Response Example #
The following JSON snippet demonstrates how the name_match_details object appears in a Real Contact 2.0 response when enabled.
{
"phone": {
"contact_grade": "A",
"is_valid": true,
"activity_score": 90,
"line_type": "Mobile",
"name_match": true,
"name_match_details": {
"match_type": "exact_match",
"is_best_name": true,
"confidence_score": 70
}
},
"email": {
"contact_grade": "A",
"is_valid": true,
"name_match": true
},
"address": {
"is_valid": true,
"name_match": false
},
"ip_address": {
"trust_score": 40,
"ip_distance_to_address": 43,
}
},
"add_ons": {
"litigator_checks": {
"phone_is_litigator_risk": false
},
"email_checks": {
"email_is_deliverable": true,
"email_age_score": 70
}
}
}Examples of Logic: #
| Input Name | Phone Associated Name(s) | phone.name_match | match_type | is_best_name | confidence_score |
| John Smith | John Smith (Primary), Jonathan Smith (Associated) | True | Exact Name Match | True | 50 |
| John Smith | Jane Smith (Primary), John Smith (Associated) | True | Exact Name Match | False | 60 |
| John Wayne | John Smith | True | First Name Match | False | 70 |
| J Smith | John Smith | True | Exact Name Match | True | 90 |
How do I enable Name Match Details? #
The Name Match Details feature is available to enterprise customers at no additional cost with our Real Contact API. This feature is not enabled by default.
To enable Name Match Details, contact your Account Manager or email support@trestleiq.com.