Give contact numbers a common comparison value

Your CRM has (415) 555-0100. An incoming contact has +1 415-555-0100. Comparing those strings directly leaves a duplicate candidate undiscovered.

match-key-phone returns 14155550100 as the match key for both. You can use that shared value to find existing records before creating another contact.

The Matchpoint endpoint costs 0.005 USDC per call, paid through x402 on Base mainnet. Route a task here when you're comparing phone formatting variants during a contact import or joining records across systems.

Keep the original number. The returned key gives your matching process a separate comparison field while preserving what the contact supplied.

Send the phone and its region

The endpoint accepts a JSON object with a required phone string and an optional region string. Here's a request body for a US contact: 

{
  "phone": "(415) 555-0100",
  "region": "US"
}

region defaults to "US". Under that default, a ten-digit number receives the +1 prefix. An eleven-digit number that already starts with 1 also produces the expected US form.

The phone string must contain something after surrounding whitespace is removed. Missing or blank values return HTTP 400; a trimmed value longer than 40 characters returns HTTP 413.

And region deserves attention. The current endpoint's handling of national numbers is limited: setting "GB" doesn't turn a British local number into a complete international number. For contacts outside the US, supply the known international number with its leading + and calling code.

Keep extensions in a separate field before sending the request. Extension digits become part of the number being normalized, which changes the resulting match key.

Read the returned fields

For the US request above, the response is: 

{
  "input": "(415) 555-0100",
  "match_key": "14155550100",
  "e164": "+14155550100",
  "country_code": "1",
  "is_valid": true
}

input contains the submitted phone string after surrounding whitespace is removed. It's useful for connecting a result to the record you're processing.

e164 contains the normalized international-style value. In this example, it's +14155550100, with punctuation removed and the US calling code added. Treat this field as a normalization result; a value appearing here doesn't establish that it's a valid number under a country's numbering rules.

country_code is the calling-code string, such as "1", rather than the region label "US". It can also be null. International calling-code extraction has limits, so verify this field before using it to assign a contact's country.

is_valid is a JSON boolean. Its current check accepts a digit count between seven and fifteen, after the endpoint's normalization steps. It doesn't establish that the number is assigned or reachable. A contact-verification workflow needs a separate check.

match_key contains the normalized digits without the leading +. Keep it as a string in your database. It's the field to compare when your immediate question is whether two phone inputs normalize to the same value.

Group candidates before merging contacts

Run both formatting variants through the endpoint and compare their returned keys: 

{
  "first_input": "(415) 555-0100",
  "second_input": "+1 415-555-0100",
  "first_match_key": "14155550100",
  "second_match_key": "14155550100",
  "same_phone_key": true
}

This is an application comparison example, separate from the endpoint's response schema.

So build the import around candidate groups. Store each returned key alongside its source record, then look for existing records with the same nonempty key. Send results with is_valid: false to a correction queue before they affect matching decisions.

A shared phone key is evidence for review. Households can share a number, and a business reception line can appear on several contacts. Require another identifying field, such as an email address, before an automatic merge.

For an agent routing this task, make the instruction explicit: normalize each contact's phone, group equal nonempty keys, and preserve each source record for the merge decision. If the task asks whether a number can receive an SMS, route that part to a service that checks reachability.