Integrate Watchlist Monitoring

Watchlist monitoring integration

Monitoring means RiskOS™ will continuously check a customer you’ve accepted against watchlists. If the lists change (a new sanction, an update to an existing record, or a removal), Socure generates an alert, which will be sent to you via webhook, and usually a case for review.

Using monitoring requires:

An entity that has first been screened using Watchlist Screening.
Watchlist Monitoring enabled for the screened entities that need to be monitored.
A webhook URL or email address to send monitoring alerts to.

Events that trigger an alert

Addition — your customer is newly added to a list.
Update — details on a list record change (e.g., new aliases, updated DOB, address).
Removal — an entity is removed from a list.

Enabling and Disabling Monitoring

There are 4 ways to enable and disable monitoring for an entity that has been screened:

Watchlist Monitoring webhook events

`monitored_search_updated`

This webhook event notifies you if any entity matches are found between your monitored entities and the watchlists you have selected in your monitoring policy.

Event-level fields

Field	Type	Description
`event_id`	string (UUID)	Unique ID for this webhook event. Used for deduplication or tracking delivery.
`event_at`	string (ISO datetime)	Timestamp when the webhook was generated.
`event_type`	string	Event type (e.g.,`watchlist_notification_monitored_search_updated`).
→ `data.id`	string	Your internal ID you passed when creating the original screening evaluation request.
→ `data.workflow`	string	Workflow name. Example: `consumer_onboarding`.
→ `data.eval_id`	string (UUID)	Evaluation ID generated in the original screening evaluation response.
→ `data.environment_name`	string	Environment (e.g., `Production`).
→ `data.globalWatchlist`	object	Watchlist enrichment details.
→ `data.referenceId`	string (UUID)	Watchlist enrichment reference ID from the original screening evaluation response.
→`data.globalWatchlist.matches`	Object	Object containing one or more lists, where each list name (e.g., `United States Arkansas Insurance Department Legal Orders`) contains match records. Each list will be detailed separately in the `matches.[listname]` table.

Match-level fields

Each webhook message contains an array of potential matches. Each watchlist source and entity combination appears under: globalWatchlist.matches[category][]

Field	Type	Description
`matches[category]`	string	Category of match (e.g., `"OFAC SDN List"`, `"PEP Data"`, `"adverseMedia"`).
→ `status`	string	Status and change date. Values: `"added date: [date]"`, `"updated..."`, etc.
→ `entityId`	string	Entity ID from Socure’s identity graph.
→ `matchFields[]`	array of strings	Fields that were matched.
→ `sourceUrls[]`	array of strings	Watchlist source URLs.
→ `matchScore`	integer	Name match score (1–100).
→`entityCorrelationScore`	integer	Entity correlation score (1–100).

Source-specific fields

Additional watchlist source-specific data is returned under: matches[category][].comments which have the same structure as the fields returned in the Watchlist Screening evaluation API response. These fields display details for each of the matches that are found against each of the lists that you are monitoring entities against, and are dynamic based on what list is matched with the screened or monitored entity.

Sample webhook response

{
    "event_id": "246149b0-129d-5774-c543-45223220659d", 
    "event_at": "2023-09-14T07:46:55.955656Z",
    "event_type": "watchlist_notification_monitored_search_updated", 
    "data": { 
      "id": "53048d83-d488-4dc3-aa59-b5701aabaffc",
      "workflow": "individual_onboarding",
      "eval_id": "135038a9-018c-4663-b432-34112119548c", 
      "globalWatchlist": {
      "referenceId": "53048d83-d488-4dc3-aa59-b5701aabaffc",
         "matches": {
            "United States Arkansas Insurance Department Legal Orders": [
               {
                  "entityId": "AbQ+/V5Rb9Nng4FhcUFLxja+8wLAbk",
                  "status": "added date: 2024-11-13",
                  "matchFields": [
                     "nameExact",
                     "dobNotOnRecord"
                  ],
                  "sourceUrls": [
                     // Socure returns sources not shown here for brevity and sensitivity.
                  ],
                  "comments": {
                     "relatedURL": [
                        "https://www.insurance.arkansas.gov/uploads/legalorders/2012-296-Suspension.pdf"
                     ],
                     "enforcementAgency": [
                        "United States Arkansas Insurance Department"
                     ],
                     "activationDate": [
                        "April 16, 2012"
                     ],
                     "offense": [
                        "Warning"
                     ],
                     "otherInfo": [
                        "LICENSE SUSPENSION"
                     ]
                  }
               }
            ],
            "United States District of Columbia Courts Active Warrant List": [
               {
                  "entityId": "AbQ+/V5Rb9Nng4FhcUFLxja+8wLAbk",
                  "status": "removed date: 2024-11-13",
                  "matchFields": [
                     "nameExact",
                     "dobNotOnRecord"
                  ],
                  "sourceUrls": [
                     // Socure returns sources not shown here for brevity and sensitivity.
                  ],
                  "comments": {
                     "enforcementAgency": [
                        "United States District of Columbia Courts"
                     ],
                     "enforcementType": [
                        "Active Arrest Warrant"
                     ],
                     "activationDate": [
                        "2010"
                     ],
                     "offense": [
                        "Warning"
                     ],
                     "otherInfo": [
                        "2010 CTF 000573"
                     ]
                  }
               }
            ],
            "United States System for Award Management Exclusions excl OFAC": [
               {
                  "entityId": "BcR+/W6Sc0Ooh5GidVGMykb+9xMBcl",
                  "status": "updated date: 2024-11-13",
                  "matchFields": [
                     "nameExact",
                     "dobNotOnRecord"
                  ],
                  "sourceUrls": [
                     // Socure returns sources not shown here for brevity and sensitivity.
                  ],
                  "comments": {
                     "activeStartDate": [
                        "2014-08-19"
                     ],
                     "exclusionProgram": [
                        "Reciprocal"
                     ],
                     "exclusionType": [
                        "Ineligible (Proceedings Pending)"
                     ],
                     "address": [
                        "CLEARFIELD; UT; 84015"
                     ],
                     "offense": [
                        "Fitness Probity"
                     ],
                     "excludingAgency": [
                        "ARMY"
                     ]
                  }
               }
            ]
         }
      }
	}
}