Use case:

When sending a message via API, there are cases where the target phone number is tied to multiple duplicate contacts. In these situations, the API request fails, and the sender cannot proceed unless the duplicate contacts are resolved first. Since the merge API requires contact IDs, but duplicate issues are surfaced at the phone-number level, businesses cannot easily automate the resolution.

Business problem:

Today, if duplicate contacts exist for the same phone number, sending a message through the API can return a 400 error stating that the phone number is already connected to a contact. This creates friction for API-based workflows, because businesses cannot automatically recover from the error or clean up duplicates in a scalable way. The current limitation is especially problematic because the merge action depends on contact IDs, while the failure is surfaced at the phone number level.

Desired outcome: