Unified Contact ID

The Unified Contact ID feature simplifies contact management by automatically grouping MSISDN-based identities (phone numbers) across SMS, RCS, and MMS channels under a single contact entity. This creates a more consistent view of your contacts and improves message delivery reliability.

How it works

When enabled, the Unified Contact ID feature ensures that contacts with the same phone number across supported channels are treated as a single entity. This is accomplished through an identity interceptor that:

Detects when a contact is created or updated with a phone number identity on one of the supported channels
Automatically appends the same phone number identity to all other supported channels for that contact
Maintains a unified view of the contact across all MSISDN-based channels

For example, if you create a contact with an SMS identity using phone number +1234567890, the system will automatically add identities for MMS and RCS using the same phone number:

Input Contact:

Copy

Copied

{
  "channelIdentities": [
    {
      "channel": "SMS",
      "identity": "+1234567890"
    }
  ]
}

Resulting Contact (with feature enabled):

Copy

Copied

{
  "channelIdentities": [
    {
      "channel": "SMS",
      "identity": "+1234567890"
    },
    {
      "channel": "MMS",
      "identity": "+1234567890"
    },
    {
      "channel": "RCS",
      "identity": "+1234567890"
    }
  ]
}

Supported Channels

By default, the following channels are supported for unification:

Activating Unified Contact ID

You can activate Unified Contact ID for new projects or for existing projects.

For new projects

For new projects with no existing contacts, you can enable the Unified Contact ID feature during project setup.

Use the Project Settings API to create project settings with the Unified Contact ID feature enabled. Make a POST call to the /v1/projects/{project_id}/settings endpoint with the following payload:

Copy

Copied

{
  "contact_settings": {
    "unified_contact_id_enabled": true
  }
}

Since there are no existing contacts in a new project, no identity conflicts will exist, and the feature can be enabled immediately.

For existing projects

For projects with existing contacts, you must first check for and resolve any identity conflicts before enabling the feature:

Check for identity conflicts using the List Identity Conflicts API by making a GET API call to the following endpoint: /v1/projects/{project_id}/contacts:identityConflicts .
If conflicts are found, you have two options:
a. Resolve conflicts manually. Use the Merge Contact API to combine conflicting contacts. To do so, make a POST API call to the /v1/projects/{project_id}/contacts/{destination_id}:merge with the following payload:
Copy

Copied
```
{
 "source_id": "contact_id_to_be_removed"
}
```
b. Delete all contacts. If you prefer to start fresh, you can delete all contacts under a project and then enable the feature. Deleting contacts will also delete all associated conversations and messages so proceed with caution. To delete all contacts, make a DELETE API call to the folllowing endpoint: /v1/projects/{project_id}/contacts:deleteAll.
Once all conflicts are resolved, enable the Unified Contact ID feature. Do so by making a PATCH call to the /v1/projects/{project_id}/settings with the following payload:
Copy

Copied
```
{
  "contact_settings": {
    "unified_contact_id_enabled": true
  }
}
```

Potential error

If you attempt to enable the Unified Contact ID feature while identity conflicts exist, the API will return an error. You must resolve all conflicts before the feature can be enabled.

An example of such an error is below:

Copy

Copied

{
  "error": {
    "code": 400,
    "message": "Cannot enable unified_contact_id feature because contact conflicts exist for project: {Project_Id}.\nPlease resolve all contact conflicts before enabling this feature.\n",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "UNIFIED_CONTACT_ID_CONFLICT",
        "domain": "conversation.api.sinch.com",
        "metadata": {
          "project_id": "{Project_Id}"
        }
      }
    ]
  }
}

Identity conflicts

An identity conflict occurs when the same phone number is associated with different contacts across different channels. For example:

Contact A has an SMS identity with phone number +1234567890
Contact B has an RCS identity with the same phone number +1234567890

These conflicts must be resolved before the Unified Contact ID feature can be enabled. The List Identity Conflicts API helps you identify these conflicts. To use this API, make a GET call to the following endpoint: /v1/projects/{project_id}/contacts:identityConflicts.

The following is an example response:

Copy

Copied

{
  "conflicts": [
    {
      "identity": "+1234567890",
      "contact_ids": ["contact_id_1", "contact_id_2"]
    }
  ],
  "next_page_token": ""
}

Impact on Contact Operations

Activating this feature has several impacts on contact management, including contact creation, contact updates, and contact retrieval.

Contact Creation

When creating a new contact with phone-based channel identities, the system will automatically enrich the contact with identities for all supported channels before storing it in the database. This happens transparently and requires no additional action from your side.

Contact Update

When updating an existing contact, the system will:

Apply your requested changes to the contact.
Re-evaluate the unified identities based on the updated contact information.
Store the enriched contact with all unified identities.

Contact Retrieval

When retrieving contacts, you'll see all the unified identities that were automatically created. This provides a complete view of all the channels through which you can reach the contact.

When the Feature Is Not Activated

The Unified Contact ID feature will not be activated in the following scenarios:

Feature is disabled for your project : This occurs when the feature flag for your specific project is set to false.
No phone-based channel identities : This occurs when the contact doesn't contain any identities on the supported unifiable channels.
Conflicting phone numbers : This occurs when a contact has multiple identities with different phone numbers. In this case, the system will log a warning and skip the unification process to avoid potential data inconsistencies. Manual merging is recommended in this scenario.

Benefits of Unified Contact ID

Enabling the Unified Contact ID feature provides several benefits:

Consistent contact view : Maintain a single view of your contacts across the supported channels, including SMS, RCS, and MMS.
Improved message delivery : Prevent delivery failures caused by channel identity conflicts.
Simplified contact management : Reduce the need for manual contact merging and maintenance.
Better conversation continuity : Ensure message history is preserved across different channels.

Best Practices

Enable on new projects : It's recommended that you enable the Unified Contact ID feature on newly created projects to avoid dealing with identity conflicts.
Carefully evaluate existing projects : For existing projects with a large number of contacts, carefully evaluate whether to merge conflicts or delete all contacts based on your specific needs.
Consistent phone numbers : Use consistent phone number formats across your application to ensure proper unification.
Regular monitoring : After enabling the feature, monitor your contact management processes to ensure they align with the new unified identity approach.
Manual conflict resolution : If you encounter warnings about conflicting phone numbers, manually review and merge the contacts as needed.

Important

Note the following:

Once enabled, the Unified Contact ID feature will automatically unify all MSISDN-based identities for new and updated contacts. This behavior cannot be selectively applied to only certain contacts within a project.
Having this feature enabled impacts performance similarly to sending messages with multiple channel identities. In other words: on campaigns that create new contacts, more information will need to be silently stored, whereas already existing contacts do not impact performance.

Troubleshooting

If you notice that contacts aren't being unified as expected:

Verify that the feature is enabled for your project.
Check that you're using supported channels for unification.
Ensure there are no conflicting phone numbers
Example of conflicting phone numbers:
Copy

Copied
```
{
 "channelIdentities": [
   {
     "channel": "SMS",
     "identity": "+1234567890"
   },
   {
     "channel": "MMS",
     "identity": "+9876543210"
   }
 ]
}
```
In this example, the contact has two different phone numbers (+1234567890 and +9876543210). This creates a conflict that prevents automatic unification. To resolve this, you should manually review the contact and decide which phone number is correct, or split it into separate contacts if both numbers are valid but belong to different individuals.

For additional assistance, contact your system administrator or Sinch support.