Verifying PII Updates

When a user submits a change of information, you may want to assess risk with Fraud vendors to understand whether to reject the update or increase the customer’s risk level.

To do this, we can set up a Source Workflow to call external vendors with the newly submitted PII elements along with other pre-existing PII that Alloy has stored for the Entity. This allows Alloy to fully assess the Entity profile without requiring you to re-submit all of their PII.

Type	Values
Monitoring Event	`person_updated` or `business_updated`
Minimum Required Fields	1. `event_status`(outside of `data` object) 2. `external_entity_id` or `entity_token` 3. `timestamp`
Recommended Fields	1. `event_lifecycle_id` 2. Any PII elements being updated

Please reference events API for a full set of supported fields.

PII Updates Request

{
    "event_type": "person_updated",
    "event_status": "pending",
    "event_lifecycle_id": "3c0a6e76-3637-4566-8d58-d9f193374d22",
    "data": {
        "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
        "timestamp": "2024-03-25T22:28:42.692Z",
        "emails": [
            {
                "email_address": "[email protected]"
            }
        ]
    }
}

Event Status

The value for event_status will determine which Source Workflow (if any) Alloy will use to evaluate the PII change event taking place. This is defined by your Event Mapping..

If your implementation supports rejecting (or pausing) the attempted PII update from taking place, your Event Mapping would be configured such that event_status: "pending" would not persist Entity information in Alloy yet, since it's still eligible to be rejected.

Hydration

Entity data is automatically hydrated when submitting a request with /events. The data is extracted based on the external_entity_id that was provided.

Since the entity was previously registered with its name, address and phone number, when submitting an update, the request will be hydrated with these elements. Both the hydrated and updated data will be surfaced under event.data{} in the response.

PII Update Response

Since we are evaluating the PII update, we can also obtain the outcome of the Source Workflow under evaluations[].summary.outcome.

When the source workflow is being utilized in an ongoing Journey, journey_applications[] will surface the Journey Application token, which represents an Alert. Along with the support of Journeys Webhooks, this allows you to easily manage the state of an Alert, and be notified for any asynchronous event such as Alert review.

{
    "status_code": 201,
    "event_request_token": "EV-w3Fy5VxnzOyUhpshW7yI",
    "_links": {
        "self": {
            "href": "/v1/events/EV-w3Fy5VxnzOyUhpshW7yI"
        }
    },
    "event": {
        "event_type": "person_updated",
        "event_status": "PROCESSED",
        "data": {
            "entity_token": "P-TfkFe6lCPkElc9Xktd3V",
            "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
            "created_at": 1711506386196,
            "person_details_updated_at": 1711508054042,
            "gender": null,
            "birth_date": null,
            "name_first": "John",
            "name_middle": null,
            "name_last": "Doe",
            "document_ssn": null,
            "document_license": null,
            "document_passport": null,
            "addresses": [
                {
                    "line_1": "41 E. 11th",
                    "line_2": null,
                    "city": "New York",
                    "state": "NY",
                    "postal_code": "10003",
                    "created_at": 1711506385710,
                    "type": "primary",
                    "evaluation_token": null
                }
            ],
            "emails": [
                {
                    "email_address": "[email protected]"
                },
                {
                    "email_address": "[email protected]"
                }
            ],
            "phones": [
                {
                    "phone_number": "+1934428189"
                }
            ],
            "type": "person",
            "_embedded": {
                "document_ssns": [],
                "birth_dates": []
            },
            "_links": {
                "self": {
                    "href": "/v1/entities/persons/P-TfkFe6lCPkElc9Xktd3V"
                }
            }
        },
        "evaluations": [
            {
                "error": null,
                "evaluation_token": "S-3P28Muud4fhMa2q54iGF",
                "workflow_token": "zW3f7QPIBfHSgkWLwwsZYDe7kBg3ScKt",
                "workflow_version_id": 11,
                "prefiltered": false,
                "summary": {
                    "result": "success",
                    "outcome": "Manual Review",
                    "tags": [
                        "info_tag: email exists",
                        "Email Risk"
                    ]
                },
                "_links": {
                    "self": {
                        "href": "/v1/evaluations/S-3P28Muud4fhMa2q54iGF"
                    }
                }
            }
        ],
        "journey_applications": [
            {
                "error": null,
                "journey_application_token": "JA-EiM42mDnJWlGMR1wSBW2",
                "journey_token": "J-FlFujbCsYMUUiXLl5aEX",
                "journey_version_id": 1,
                "source_evaluation_tokens": [
                    "S-3P28Muud4fhMa2q54iGF"
                ],
                "_links": {
                    "self": {
                        "href": "/v1/journeys/J-FlFujbCsYMUUiXLl5aEX/applications/JA-EiM42mDnJWlGMR1wSBW2"
                    }
                }
            }
        ]
    }
}

Finishing the Event Lifecycle

If the PII change event you submitted for screening is ultimately successful, you'll need to make another request to Alloy to persist the updated PII to the Entity Profile, in order to keep both systems in sync. In this example, the event_status: "successful" would be configured to do this, but would not be configured to trigger a Source Workflow, since the PII has already been screened earlier in the lifecycle.

{
    "event_type": "person_updated",
    "event_status": "successful",
    "event_lifecycle_id": "3c0a6e76-3637-4566-8d58-d9f193374d22",
    "data": {
        "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
        "timestamp": "2024-03-26T06:12:32.000Z",
        "emails": [
            {
                "email_address": "[email protected]"
            }
        ]
    }
}