Entity Merging

Depending on your use case, there may be scenarios where you have two separate Entities that really should be represented as a single Entity record. You can use Alloy's Entity Merge API to combine Entity records and consolidate to a single record.


curl -X "POST" "https://sandbox.alloy.co/v1/entities/merge" \
     -u WORKFLOW_TOKEN:WORKFLOW_SECRET \
     -H 'Content-Type: application/json' \
     -d $'{
       "event_type": "person_updated",
       "data": {
          "primary_external_entity_id": "yourExternalEntityId",
          "secondary_external_entity_id": "yourOtherExternalEntityId"
       }
}'

When merging, you'll need to specify one Entity as the primary record during the merge. This designation dictates which Alloy Entity Token will be retained. If both the primary and secondary Entities have External IDs assigned, both IDs will carry over to the merged Entity record, however the primary External ID will be sourced from the primary merge Entity.

Once merged, all activity and Alloy data on the secondary Entity will be carried over and aggregated into the primary Entity record.

If two entities are merged which have different information, the following behavior will be followed:

  • If the information that differs is a record where the Alloy schema accepts multiple values (e.g. Addresses), both addresses will be retained.
  • If the information that differs is a record where the Alloy schema only accepts a single value, the primary entity's value will be retained.