Retroactively Assigning an External Entity ID

If you don’t assign a unique identifier for an Entity until after initial account opening, you can still link your External ID to the Alloy Entity after it’s been created by submitting a person_updated event to the Events API:

curl -X "POST" "https://sandbox.alloy.co/v1/events" \
     -u WORKFLOW_TOKEN:WORKFLOW_SECRET \
     -H 'Content-Type: application/json' \
     -d $'{
       "event_type": "person_updated",
       "data": {
          "entity_token": "{{entity_token}}",
          "external_entity_id": "yourExternalEntityId",
          "timestamp": "2024-01-01T00:00:00Z",
       }
}'

Note that this endpoint requires the Alloy Entity Token or the External Entity ID as a parameter. If the Entity doesn’t yet have an External Entity ID assigned, note this means you’ll need to use the Entity Token in your request.

After an External Entity ID is assigned to an Entity, you cannot change the value later. However, you can add additional External IDs to the same Entity through Entity Merging or by using the external_entity_ids[] field on person_updated requests via the Events API:

{
       "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"
       }
}

For more use cases using multiple External IDs, see the next page.

Legacy Endpoints

You can also use the PATCH /entities/persons endpoint for appending an External ID for the first time:

curl -X "PATCH" "https://sandbox.alloy.co/entities/persons/{{entity_token}}" \
     -u WORKFLOW_TOKEN:WORKFLOW_SECRET \
     -H "Content-Type: application/json" \
     -d $'{
       "external_entity_id": "yourExternalEntityId"
}'