Skip to main content
Question

Issues with search contacts API

  • April 24, 2026
  • 1 reply
  • 20 views
chrismadufor

Hi friends!

I am implementing a custom solution and need to be able to search and identify contacts on Front with their phone number.

I have tried https://api2.frontapp.com/contacts/alt:phone:[Number] returns an exact result if the number exists. However in many cases the number doesn’t exist and it return a 404 error which causes the custom template I am building to crash.

I have also tried https://api2.frontapp.com/contacts?q=[Number] but the problem is that the query is ignored and all the contacts we have are returned every time and these contacts have no connection to the query. This is really not helpful. If this endpoint can return only contacts that have the query as a handle or name, that will be a lot more helpful.

Has anyone had a reason to do something similar or is there anything I must have missed with searching contacts with the query method?

1 reply

Maxime Haudebert
Forum|alt.badge.img+5

Hi Chris!

Thanks for sharing your experience with the phone number search. Getting a 404 error when no contact is found is actually expected behavior for the exact-alt phone lookup. To keep your template running smoothly, it’s best to treat that response as simply "no contact" rather than an error.

Here’s how you can improve your integration:

  • Use the exact-phone endpoint for precise matches. When it returns not-found, handle this gracefully so your template doesn’t crash.

  • If there’s no exact match, try the /contacts query endpoint as a backup. Before calling it, clean up the phone number by removing non-digit characters and testing versions with or without country codes or leading zeros. 

    • Here is an example query: /contacts?q=phone%3D%2B33699665544 for number +33699665544. /contacts?q=phone=+33699665544 would also work

  • Normalize phone numbers on your end before making API requests to boost matching accuracy.

  • Set up a clear flow: first attempt the exact lookup; if you find a match, use it. If not, fall back to the query search and pick the best result if available. Otherwise, treat it as no contact.

Following these steps will help your custom setup handle missing numbers smoothly while still exploring broader matches when needed.

Feel free to reach out if you want to dig in deeper or need more help!

Terms & ConditionsAccessibility statement