Multiple External Entity IDs

Alloy supports having multiple External IDs assigned to a single Entity record. This feature is helpful in scenarios where multiple systems may need to interact with Alloy using their own identifiers that differ across each system.

Each External ID assigned to a given Entity still must be unique to that Entity and cannot be re-used across multiple Entity records. Additionally, one of the External IDs will be designated as the primary External ID; the primary designation dictates what's visible in the Alloy UI as well as what's returned in API calls.

You can use any of the External IDs to specify the Entity on requests to the Events API, Journeys API, Evaluations API, and Entities APIs.

How to Assign Multiple IDs

Using Person Updated Events

After an Entity record is created, you can use the Events API to append additional External IDs via person_updated or business_updated Events.

In your request, you must specify either the Entity Token or an already assigned External ID on your request in addition to the external_entity_ids[] field with your multiple identifiers:

{
       "event_type": "person_updated",
       "data": {
          "entity_token": "P-FsGCs0P9aytzrMe7vLVh",
          "external_entity_ids": [
            {
                "external_entity_id": "yourExternalEntityId",
                "designation": "primary"
            },
            {
                "external_entity_id": "yourOtherExternalEntityId"
            }
          ],
          "timestamp": "2024-01-01T00:00:00Z"
       }
}

{
       "event_type": "person_updated",
       "data": {
          "external_entity_id": "yourExternalEntityId",
          "external_entity_ids": [
            {
                "external_entity_id": "yourExternalEntityId",
                "designation": "primary"
            },
            {
                "external_entity_id": "yourOtherExternalEntityId"
            }
        ],
          "timestamp": "2024-01-01T00:00:00Z"
       }
}

{
       "event_type": "person_updated",
       "data": {
          "external_entity_id": "yourExternalEntityId",
          "external_entity_ids": [
            {
                "external_entity_id": "yourExternalEntityId"
            },
            {
                "external_entity_id": "yourOtherExternalEntityId",
                "designation": "primary"
            }
        ],
          "timestamp": "2024-01-01T00:00:00Z"
       }
}

Using Entity Merging

When merging two Entities , the resulting Entity will automatically inherit the External IDs for both Entities associated with the merge. The primary External ID will be inherited from the primary Entity specified during the merge.