Finding contacts using phone numbers through HubSpot API

[danwilson85]

I know that the HubSpot API has ways to look up contacts using their name or email address. But I need to find contacts based on their phone numbers instead.

I’ve been working with the contact search endpoints, but I’m not sure if phone number lookup is supported. Has anyone successfully searched for contacts using phone numbers through the HubSpot API? I need to match customer records in my system with HubSpot contacts using only phone numbers as the identifier.

What would be the best approach to accomplish this kind of search functionality?

[Hermione_Book]

HubSpot’s API makes phone searches a pain because of how it handles formatting. Hit this same issue last year during a CRM integration. The problem? HubSpot strips all formatting when storing numbers. So (555) 123-4567 becomes 5551234567 in their system. You’ve got to strip non-numeric characters from your search input before querying. International numbers with country codes make it even messier. I built a preprocessing function that tries different format combinations if the first search comes up empty. Once you work around these formatting quirks, the search API actually performs pretty well.

[Emma_Galaxy]

Yes, it’s possible to search for contacts using phone numbers in HubSpot’s API. The documentation might not be explicit, but utilizing the search endpoint with phone as a filter is the way to go. Ensure you properly structure your request by including the desired phone field (like phone or mobilephone) in the properties array and adopt the correct number format. HubSpot can be particular about formatting, so if initial attempts yield no results, try different variations. For instance, numbers formatted with dashes or parentheses are unlikely to match plain numbers. A useful tip is that you can concurrently search multiple phone fields if you’re uncertain where the number is stored.

[wanderingWeasel]

The Problem: You need to find HubSpot contacts based on their phone numbers using the HubSpot API, but you’re encountering difficulties due to inconsistent phone number formatting.

Understanding the “Why” (The Root Cause): The core issue is HubSpot’s internal handling of phone numbers. The API stores phone numbers without formatting (e.g., (555) 123-4567 becomes 5551234567). If your search requests use differently formatted numbers, the API won’t find a match. This inconsistency makes direct searching challenging and necessitates preprocessing of your phone numbers before querying the API.

Step-by-Step Guide:

1. Normalize Phone Numbers: Before making any API calls, create a function to clean and standardize your phone numbers. This function should remove all non-numeric characters (parentheses, hyphens, spaces, etc.) and ideally handle international country codes.

   function normalizePhoneNumber(phoneNumber) {
       return phoneNumber.replace(/\D/g, ''); //Removes all non-digit characters
   }
   
   let unformattedNumber = "(555) 123-4567";
   let formattedNumber = normalizePhoneNumber(unformattedNumber); //formattedNumber will be "5551234567"
   

2. Make the API Call: Use the HubSpot contact search API endpoint. Include the normalized phone number in your request, targeting either the phone or mobilephone property (or both, if uncertain where the number is stored).

   // Example using fetch (replace with your preferred HTTP client)
   fetch('https://api.hubapi.com/contacts/v1/search/query', {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'Authorization': `Bearer ${YOUR_API_KEY}` // Replace with your API key
       },
       body: JSON.stringify({
           q: `phone:${formattedNumber}` // or `mobilephone:${formattedNumber}` or both
       })
   })
   .then(response => response.json())
   .then(data => {
       // Process the search results
       console.log(data);
   })
   .catch(error => console.error('Error:', error));
   

3. Handle Multiple Formats (Optional but Recommended): If the initial search fails, consider adding logic to try variations of the phone number format (e.g., adding “+1” for US numbers). This iterative approach increases the chances of a successful match.

4. Error Handling: Implement robust error handling to gracefully manage cases where no match is found or API errors occur. Logging detailed error messages will aid in debugging.

Common Pitfalls & What to Check Next:

• API Key: Double-check that your HubSpot API key is correct and has the necessary permissions.
• Property Names: Verify that phone or mobilephone are the correct property names in your HubSpot contact objects. Use the HubSpot API documentation to confirm.
• Rate Limits: Be mindful of HubSpot’s API rate limits to avoid exceeding allowed requests per minute/hour. Implement delays or queuing if necessary.
• Data Quality: Ensure the phone numbers in your system are accurate and consistently formatted to avoid unnecessary complexity in your normalization function.

Still running into issues? Share your (sanitized) config files, the exact command you ran, and any other relevant details. The community is here to help!