When using the Establish Identity API to merge a mobile contact into a named contact, you may find that instead of performing the merge, the system writes the lookup key value onto the mobile contact. No error message is returned. This article explains why this happens and how to prevent it.

What causes this

This is expected behavior. When a call is made to the Establish Identity API with a lookup key value that does not currently exist in the database, the system automatically assigns that lookup key to the target contact specified in the merge request. Because the lookup key has no existing match in the database, the system adopts it onto the targeted mobile contact rather than performing a merge.

No error is returned because the API call itself is valid — the system processes the request successfully, it simply cannot find a matching record to merge.

Example

The following payload illustrates this scenario:

curl --location --request PUT 'https://api-campaign-eu-1.goacoustic.com:443/rest/databases/{database_id}/establishidentity/{mobile_contact_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_token}' \
--data '{
  "identity": {
    "name": "Lead_ID",
    "value": "{lookup_key_value}"
  },
  "useCrmContactAsWinner": "true",
  "mergeEvents": "false"
}'

If the Lead_ID value provided does not match any existing contact in the database, the system writes that value onto the mobile contact instead of merging it. The API response returns a winnerRecipientId and winnerChannelIdentifier without indicating that a merge did not occur.

How to prevent this

This behavior cannot be modified — it is by design. To ensure merges work as expected:

• Pre-populate your database with all identified contacts before making Establish Identity API calls. This ensures the required lookup keys are already in place and available when the merge is attempted.
• Verify lookup key values exist in the database before submitting merge requests. If the lookup key is not already associated with a contact, the merge will not occur.