Handling duplicate discoveryKeys
All contacts in Engage must have unique discoveryKeys. If a discoveryKey is not unique, this can block contact creation and prevent personalization from working correctly. This article explains when validation errors occur, how to resolve them, and what to do if duplicates exist in your environment.
When a validation error occurs
A discoveryKey validation error means that the discoveryKey you tried to save already exists in Engage. New or updated contacts are validated when added through the Contact API v2/v3. Other interfaces for creating or updating contacts, such as bulk endpoints, are not affected by this validation.
Example error message:
{
"errors": [
{
"code": "DuplicateDiscoveryKey",
"message": "The discoveryKey already exists and must be unique."
}
]
}If you receive this error repeatedly, it may indicate that your website is not assigning unique discoveryKeys to visitors. This can sometimes be related to how your site generates and stores identifiers, including through connection with integrations (for example, to Voyado Elevate).
Resolving the issue
Your site must always assign the visitor a new, unique discoveryKey. Once generated, this new discoveryKey must be consistently used in:
the Contact API request
the visitor's cookie
any other system where discoveryKeys are stored (such as databases, Engage, Elevate)
How this is implemented is site-specific, but the goal is always the same: to ensure that every visitor and member has a unique discoveryKey across all systems.
Handling existing duplicates
Before cleaning up existing duplicates:
Make sure no new duplicates are being added.
Confirm that the normal flows for adding and updating contacts work correctly (without disabling validation).
When e-com / 3rd party system is the master
If your e-commerce platform or another system is the master of discoveryKey, duplicates must be resolved there first. Once corrected, you will then send the updated discoveryKeys to Engage.
When Engage is the master
If Engage is the master of your discoveryKeys, duplicates can be removed directly within Engage. Contact Voyado Support for assistance with this process..
Updating duplicates instead of removing them
If you prefer to update duplicate records rather than remove them, the master system must:
Identify which contacts to update.
Send the changes to Engage (via API or integration).
Depending on the scale and complexity, this process may require assistance from Voyado Support to export duplicate lists or perform bulk updates.