Home › Knowledge base › OpenSanctions
Explore Knowledge Base

OpenSanctions

03. 01. 2025

An Integration with OpenSanctions as a sanction lists service provider is implemented through the NodeRed low-code solution.

The integration uses the Consolidated list of sanctioned entities designated by different countries and international organizations. Bulk Downloads contain the full set of entities contained in one dataset. OpenSanctions provides updated files once a day at the same location. Also, the internal SDK APIs and logic for automatic or on-demand checks were extended.

So the SDK system implemented the technical integration through the NodeRed solution to check Customers via OpenSanctions Consolidated List and embedded it into the KYC process within the SDK system.

How to start using the Integration

  1. The current implementation uses the free option Bulk download of the Consolidated Sanctions from the OpenSanctions provider. To use different provider options (e.g. API) – make an Agreement with the provider and get credentials. All features that will be available from the vendor (OpenSanctions) to the client (for both, the source code or cloud clients) depend on the client’s needs and their agreements with the vendor (OpenSanctions). After the agreement, the service provider provides the client with the credentials to access the Test and Production Environment.
  2. Set up the provider connectivity settings in the NodeRed instance. Set up the system configuration file. Provide access for NodeRed to certain S3 buckets.
  3. Set up the connectivity settings between Kafka`s and NodeRed instances. Provide access for NodeRed to certain Kafka topics with required rights (read/write)

How it works

After the User of the SDK platform provides User Profile data and uploads the documents within the front-end app (web or mobile) sanctions checks can be performed in two modes:

  • continuous (e.g. one time per day, timer configured in the NodeRed node settings level and can be changed)
  • On-demand by the Compliance manager

Continuous Sanctions List checks

The first time when the integration is launched NodeRed downloads all files with the Sanctions list from the OpenSanctions (Bulk download option) and uploads it to the S3 file storage.

Each time when the timer is processed NodeRed checks the size of the particular file on the OpenSanctions resource and compares it with an existing file in SDK S3 storage.

If the file size is changed (which means that file content was changed) NodeRed downloads the file from OpenSanctions again and uploads it to SDK S3 storage. If the file size was not changed the NodeRed skips the current file and checks another file (all files will be processed in the same way one by one).

Further NodeRed calls SDK API to obtain a list of all business users (Individual and Merchant) in the system and check it with persons listed in the Sanctions list files by the following parameters: First Name, Last Name, and Company Name (for Merchant only).

If a match (both, First and Last Name, and Company Name for Merchants) is detected NodeRed calls SDK API to create a note related to the user with the content of all matched records from the Sanctions list file. The Compliance manager will receive the notification about the Sanctions list matches detection.

On-demand Sanctions List checks

The Service User with relevant permissions (e.g. Compliance Manager) within the SDK system initiates checks for certain Users by the Sanctions List provided by the OpenSanctions. The SDK submits user data to Kafka`s topics (according to the conditions). After that the NodeRed system reads the topics, processes the data and checks matches with the Sanctions List file (the current file version, stored at the S3 will be used). If matches are detected the NodeRed calls SDK APIs to create a note related to the user with matched details in the response and to notify Compliance about the user listed in the Sanctions list. Compliance can review the notes and decide further user identification status.

OpenSanctions

 

OpenSanctions

 

Supported operations

The OpenSanctions integration in the SDK platform supports the Consolidated Sanctions Bulk download option of the OpenSanctions service (Consolidated Sanctions documentation). The supported methods of this integration can be easily extended according to the business requirements after elicitation.

Flow supported on the Test Environment

On-demand Sanctions List checks

The Service User with relevant permission (e.g. Compliance Manager) can submit user profile data for checking by the OpenSanctions service. After the checks, in case matches are detected the System will create notes with match details available for Compliance manager review (for further manual handling).

In the test flow implementation, the users check by their First name and Last name (plus the Company name for the Merchant).

Continuous Sanctions List checks are deactivated on the Test Environment. To check this flow connect with the SDK.finance team.

Business process and APIs flow

Integration setup

As an Administrator of the platform:

  1. Check the availability of the KYC Integration Service in the SDK Core configuration – in a  configuration file

Check property to confirm, that the kyc-integration service is available and Kafka topic is specified at your system configuration:

kyc-integration:
 service:
   enabled: ${KYC_INTEGRATION_ENABLED:true}
   kafka:
     topic: ${KAFKA_KYC_INTEGRATION_TOPIC:user-profile-data}

Check that complyAdvantage provider is specified in the property (use GET /v1​/kyc-providers to check)

providers: 
- complyAdvantage
  1. Check NodeRed instance availability and set up credentials on the NodeRed environment variables (to connect to the SDK S3 storage). File management is performed via NodeRed custom node and AWS SDK for JavaScript.
  2. Check Kafka instance availability

There are preliminary steps that must be done as part of integration settings before the checks via the OpenSanctions list will be performed by the Compliance Manager.

On-demand flow: Compliance Manager on-demand initiates the User check by OpenSanctions sanctions list service provider from the SDK platform

  1. As a Business User:
  1. Register in the SDK system
  2. Provide user profile data at least User name (First and Last) and Company name (for Merchant users) must be provided to perform checks
  3. Upload identification documents for verification after documents uploading the user DocumentApprovalStatus=IN_VERIFICATION
  1. As a Compliance Manager (after the User uploads documents during the onboarding process):
  1. The Compliance Manager reviews and confirms the user’s documents after Compliance approves DocumentApprovalStatus is “APPROVED” and the system OrganizationStatus is “pending” (you can use API PATCH /v1​/profiles​/{userId} for manual OrganizationStatus updating)
  2. The Compliance Manager decided to check the User by Sanctions List and selects OpenSanctions from the list of available providers (call API GET /kyc-providers to get a list of available providers).
  3. After that Compliance calls POST /profiles/{userId} with provider_key=openSanctions to initiate checks. The System submits user information to the user-profile-data topic.
  4. The NodeRed System reads the data from user-profile-data and performs checks with sanctions List files (that are stored in the SDK S3 file storage).
  5. After the check is done the NodeRed System submits the check details to separate topics (user-profile-data-response-sanctions and user-profile-data-response-sanctions-errors due to receive results) and calls SDK API POST​/v1​/users​/note to make notes regarding the current user and API POST /notification/sanctions to notify Compliance about user listed in Sanctions list. The Compliance Manager receives notification and can review notes with match details via UI or API GET ​/v1​/users​/note​/{userId} for further manual handling.

The Sanction list matches have no impact on the DocumentApprovalStatus or OrganizationStatus.

Required conditions to submit user profile data to Sanctions list checks MANUALLY:

  • call POST /v1​/profiles​/{userId} with parameter providerKey=openSanctions
  • openSanctions provider is specified in the property (use GET /v1​/kyc-providers to check)
providers: 
  - openSanctions
    property
kyc-integration:
 service:
   enabled: ${KYC_INTEGRATION_ENABLED:true}
   kafka:
         topic: ${KAFKA_KYC_INTEGRATION_TOPIC:user-profile-data}
DocumentApprovalStatus = APPROVED
OrganizationStatus=pending

if all conditions are satisfied the system submits the User Profile data to the topic user-profile-data.

NodeRed flows behaviour for On-demand flow depending on the checks result:

  • if a match is detected by both parameters (First and Last Name, plus Company Name for Merchants) NodeRed creates a note related to the user with the content of the matched record from the Sanctions list file, one note for each matched record (and submits this content to a user-profile-data-response-sanctions topic). Also, NodeRed notifies the Compliance Manager about sanctions list match (notification will be sent about a particular user, that is listed in the Sanctions list) 
  • if no match is detected the NodeRed creates a note “Sanctions list: No match“ (and submits this note to a user-profile-data-response-sanctions topic)

Continuous flow: NodeRed performs Sanctions List checks of all users of the SDK System one time per day continuously (configurable timer on the NodeRed side)

  1. NodeRed as a System:
  1. The first time when the integration is launched NodeRed downloads all files with the Sanctions list from the OpenSanctions (Bulk download option) and uploads it to the S3 file storage.
  2. Each time the timer is processed NodeRed checks the file size on the OpenSanctions resource and compares it with an existing file in SDK S3 storage.
    1. If the file size is changed (which means that file content was changed) NodeRed downloads the file from OpenSanctions again and uploads it to SDK S3 storage
    2. If the file size was not changed the NodeRed skips the current file and checks another file (all files will be processed in the same way one by one)
  3. NodeRed calls SDK API POST /users/sanctions/view to obtain a list of all business users (Individual and Merchant) in the system and check it with persons listed in the Sanctions list files by the following parameters: First Name and Last Name and Company Name (for Merchant only).

NodeRed flows behaviour for Continuous flow depending on the checks result:

  • If a match is detected (both, First and Last Name, and Company Name for Merchants) NodeRed calls SDK API POST​/v1​/users​/note to create a note related to the user with the content of the matched record from the Sanctions list file (one note for each matched record) and submits this content to a certain topic, all matches in one message). NodeRed calls API POST /notification/sanctions to notify the Compliance Manager about the fact that the Sanctions list detected matches (notification about each user separately).
  • If no match is detected the NodeRed submits this note to a certain topic (without note creation)

Compliance Manager notification

Subject: Sanctions list match detected

To: Compliance manager email (you can change or add emails in the configuration application.yaml: notifications.email.compliance.to)

Message:

“Sanctions list match detected for user [firsName lastName] with user ID [userId]. Compliance manager review required.

Sincerely,

[applicationName] support – [supportEmail]”

See more about available Compliance Manager notification

List of APIs (SDK and OpenSanctions) which are used to check users via the OpenSanctions

SDK APIs Open Sanctions APIs
API Description API Description
POST /v1​/profile-documents​/view View all profile documents    
POST /v1​/profile-documents​/{profileDocumentId}​/approve Approve the profile document    
PATCH /v1​/profiles​/{userId} Update organization status (user identification status)    
POST /profiles/{userId} To send user profile data for manual sanctions list checks    
GET /kyc-providers To get available KYC and Sanctions List providers    
POST /users/sanctions/view To obtain a list of all business users (Individual and Merchant) in the system, with parameters: First/Last name, Company name, User ID, Role.    
POST /notification/sanctions To notify the Compliance Manager about the Sanctions list matches detection.    
POST /v1​/users​/note To create notes about user    
GET ​/v1​/users​/note​/{userId} To get notes about user    
    Consolidated Sanctions. Bulk download option Consolidated list of sanctioned entities designated by different countries and international organisations. This can include military, trade and travel restrictions.

This collection combines all designated entities from the various sanctions lists included in OpenSanctions. It represents the broadest set of sanctioned people, companies and other assets that is designated globally.

Virtually all sanctions lists are based on the UN Security Council List, and add further listings based on national policies.

In SKD integration current APi is used by NodeRed to download all sanctions list data from OpenSanctions by the scheduled timer.