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": "77777777-7777-7777-7777-777777777777",
   "event_at": "2026-04-01T09:00:00.000Z",
   "event_type": "watchlist_notification_monitored_search_updated",
   "data": {
     "id": "Effectiv-Test-combined-hits_abc123",
     "workflow": "individual_onboarding",
     "eval_id": "f1234567-abcd-4567-89ef-0123456789ab",
     "reviewer_id": null,
     "environment_name": "Production",
     "globalWatchlist": {
       "referenceId": "98765432-dcba-4321-fedc-ba9876543210",
       "matches": {
         "OFAC SDN List": [
           {
             "entityId": "ZaP+/U4Q8ZQsYGxKZVMIsFKF",
             "status": "added date: 2026-04-01",
             "matchScore": 100,
             "entityCorrelationScore": 99,
             "matchFields": ["nameExact", "dobExact", "akaExact"],
             "sourceUrls": ["https://sanctionssearch.ofac.treas.gov/"],
             "comments": {
               "name": ["VLADIMIR PUTIN"],
               "aka": ["Vladimir Vladimirovich Putin", "V. Putin", "Wladimir Putin"],
               "dateOfBirth": ["1952-10-07"],
               "placeOfBirth": ["Leningrad, Russia"],
               "countryCodes": ["RU"],
               "offense": ["Sanction"],
               "entityType": ["Individual"],
               "program": ["RUSSIA-EO14024"],
               "designationDate": ["2022-02-25"],
               "issuingAuthority": ["U.S. Department of the Treasury"],
               "otherInformation": ["President of the Russian Federation"]
             }
           }
         ],
         "United Nations Consolidated List": [
           {
             "entityId": "ZaP+/U4Q8ZQsYGxKZVMIsFKF",
             "status": "added date: 2026-04-01",
             "matchScore": 100,
             "entityCorrelationScore": 99,
             "matchFields": ["nameExact", "dobExact", "akaExact"],
             "sourceUrls": ["https://www.un.org/securitycouncil/content/un-sc-consolidated-list"],
             "comments": {
               "name": ["VLADIMIR PUTIN"],
               "aka": ["Vladimir Vladimirovich Putin", "V. Putin", "Wladimir Putin"],
               "dateOfBirth": ["1952-10-07"],
               "placeOfBirth": ["Leningrad, Russia"],
               "countryCodes": ["RU"],
               "offense": ["Sanction"],
               "entityType": ["Individual"],
               "issuingAuthority": ["United Nations Security Council"],
               "otherInformation": ["President of the Russian Federation"]
             }
           }
         ],
         "PEP Data": [
           {
             "entityId": "ZaP+/U4Q8ZQsYGxKZVMIsFKF",
             "status": "added date: 2026-04-01",
             "matchScore": 100,
             "entityCorrelationScore": 77,
             "matchFields": ["nameExact", "akaEquivalent", "akaExact"],
             "sourceUrls": ["http://putin.kremlin.ru/", "https://www.wikidata.org/wiki/Q7747"],
             "comments": {
               "name": ["VLADIMIR PUTIN"],
               "aka": ["Vladimir Vladimirovich Putin", "PUTIN, Vladimir", "Wladimir Putin"],
               "dateOfBirth": ["1952-10-07"],
               "birthPlace": ["Saint Petersburg, Russia", "Leningrad"],
               "countryCodes": ["RU"],
               "pepClass": ["PEP Class 1"],
               "offense": ["Pep Class 1"],
               "entityType": ["Individual"],
               "politicalPosition": ["President of the Russian Federation", "Prime Minister of Russia"],
               "classification": ["National government (current)"],
               "occupancyStatus": ["current"],
               "sourceName": ["United Nations Protocol Service (DGACM)", "Wikidata"]
             }
           }
         ],
         "adverseMedia": [
           {
             "entityId": "ZaP+/U4Q8ZQsYGxKZVMIsFKF",
             "status": "added date: 2026-04-01",
             "matchScore": 100,
             "entityCorrelationScore": 77,
             "matchFields": ["nameExact"],
             "sourceUrls": ["https://www.reuters.com/", "https://www.bbc.com/news"],
             "comments": {
               "name": ["VLADIMIR PUTIN"],
               "aka": ["Vladimir Vladimirovich Putin"],
               "dateOfBirth": ["1952"],
               "country": ["Russia"],
               "countryCodes": ["RU"],
               "entityType": ["individual"],
               "offense": ["V2 Financial Aml Cft,V2 Fraud Linked,V2 General Aml Cft,V2 Violence Aml Cft"],
               "snippet": ["President Vladimir Putin ordered a military operation in Ukraine. Russian forces began an attack on Ukraine. That attack is a blatant violation of the territorial integrity, sovereignty and independence of Ukraine."],
               "title": ["Russia-Ukraine conflict: Putin orders military operation", "International sanctions imposed on Russian officials"],
               "date": ["2022-02-24T00:00:00Z", "2022-02-25T00:00:00Z"]
             }
           },
           {
             "entityId": "XbQ+/V5RS2u/h4CiZFYstAd/6Q4GDlS",
             "status": "added date: 2026-04-01",
             "matchScore": 82,
             "entityCorrelationScore": 31,
             "matchFields": ["nameEquivalent"],
             "sourceUrls": ["https://www.local12.com/news", "https://www.courtlistener.com/"],
             "comments": {
               "name": ["VLADIMIR Mutin"],
               "aka": ["Vladmir Mutin", "V. Mutin"],
               "dateOfBirth": ["1988"],
               "country": ["United States"],
               "countryCodes": ["US"],
               "entityType": ["individual"],
               "offense": ["V2 Violence Aml Cft"],
               "snippet": ["Vladimir Mutin, 37, of Cincinnati, Ohio, was charged with aggravated assault following an altercation outside a downtown bar. Mutin allegedly struck another individual with a blunt object, causing serious bodily injury. He was arraigned in Hamilton County Municipal Court and released on bond pending trial."],
               "title": ["Cincinnati man charged with aggravated assault following downtown altercation"],
               "date": ["2026-02-14T00:00:00Z"]
             }
           }
         ]
       }
     }
   },
   "watchlist_case_id": "combined-hits-case-001"
 }