Feature Request: Allow additional fields to be returned by /api/v2/contacts/autocomplete

Product
, ,
1

Hi Freshworks team,

We’re using the following endpoint to implement contact autocomplete:

GET /api/v2/contacts/autocomplete?term=<searchText>

The endpoint works well for finding matching contacts, but it only returns a minimal set of fields.

As far as I can tell, this is also the only Contacts API endpoint that supports searching by a search term (i.e. prefix/partial matching across contact fields). The Search Contacts API doesn’t appear to support this type of lookup, so contacts/autocomplete is the only practical option for implementing a responsive contact picker.

The issue is that sometimes there is a requirement to display only contacts that satisfy certain criteria (in our case, contacts that have an email address). Since the autocomplete response doesn’t provide enough information to determine this, we have to make an additional GET /api/v2/contacts/{id} request for every returned contact before we can populate the autocomplete results. This means that a single autocomplete search may generate dozens of additional API requests, which doesn’t scale well and increases the likelihood of hitting API rate limits.

I understand that the autocomplete endpoint is intentionally lightweight and isn’t expected to return every contact field.

However, it already returns some contact information beyond just the contact ID and name (such as phone number), so it seems reasonable to make other commonly used fields like emailavailable as well, either by default or through an optional parameter if it needs to maintain current behaviour for any reason

For example:

GET /api/v2/contacts/autocomplete?term=<searchText>&fields=id,name,email

or

GET /api/v2/contacts/autocomplete?term=<searchText>&include=email

This would remain fully backward compatible while significantly reducing the number of API requests required for common autocomplete scenarios.

Is there a specific reason the endpoint is intentionally limited to its current response, or could this be considered for a future enhancement?

Thanks so much!

2

Hi @mmi, valid concern, and thanks for the detailed write-up.

Current behavior
/api/v2/contacts/autocomplete?term= is intentionally lightweight. Per the API docs, the response includes id and name only - there is no fields or include parameter today. If you’re seeing phone in responses, that may be account-specific; don’t rely on it.

Why it’s limited
Autocomplete is optimized for fast, typeahead-style lookups (token-based name match). Full contact objects would increase payload size and latency at scale.

Alternatives today

Approach Trade-off
GET /api/v2/search/contacts?query= (Filter Contacts, Beta) Returns full records including email; supports filters like "email:'john@'". Not a name autocomplete - no prefix/typeahead UX. Indexing can lag a few minutes.
Lazy fetch on select Call GET /api/v2/contacts/{id} only when the user picks a result - avoids N calls per keystroke.
Client/server cache Cache contact details by ID after first fetch to cut repeat lookups.

On your enhancement request
An optional fields or include=email param would be backward compatible and would help common picker scenarios. We don’t have a public timeline, but this is reasonable product feedback - we’ll route it to the API team.

Practical recommendation for now: use autocomplete for name search, then fetch contact details on selection (or cache), rather than enriching every autocomplete hit upfront.