FinScan Web Services API
Getting Started Guide.
Getting Started Guide.
Integrating compliance workﬂows with your internal processes, especially those most closely related to customer experience, is critical. It’s not only vital to your compliance and risk management process, but also for keeping your customers happy and coming back to you and not one of your competitors.
FinScan’s compliance solutions can be integrated via web services with any internal or external IT system to enable it to call out to FinScan, retrieve the results, and perform a compliance screening search in real time or via periodic batch updates.
This allows for eﬃcient and safe customer onboarding from all entry points and protects your organization on all fronts with real-time screening. Plus, FinScan’s advanced and eﬃcient web service technology enables easy integration and deployment while minimizing impact on your IT resources.
Our best practice integration methodology, based on our 50 years of successful migration experience:
Web services interfaces are provided for organizations that want to integrate FinScan’s watch list screening (e.g., OFAC, FinCEN, OIG, GSA, etc.) into their existing applications. Our web services interfaces follow the standards authored by the W3C and may be accessed from any environment that is able to issue a web services call. FinScan supports both REST and SOAP calling conventions.
Options for the web services are conﬁgured through the web page maintenance interface that comes with FinScan. More information is provided here describing how FinScan needs to be configured to support web services operation. In addition, human users may invoke these same services manually through the web page interface in cases where backend application integration is not required.
The FinScan Wrapper API is a stateless web service that supports both REST and SOAP calling conventions. The REST API will accept both XML and JSON input, while the SOAP API will accept XML only. The production endpoint is supported solely on HTTPS. All requests to the production endpoint need to be SSL/TLS compliant. The base URL for the API will depend on the location of the FinScan server you are accessing. It can be your local OnPremise installation or one of the 5 data centers on Azure we operate around the world. For the SandBox a URL is provided that you can use to become familiar with the operation of the FinScan web services. The access URL will take the form of:
The FinScan Web Services (affectionately called “The Wrapper”) are actually a set of externally exposed web services that have been optimized around the common functions that are typically needed to support name screening transactions. The FinScan Application server actually exposes hundreds of web services as the entire architecture is designed around the ease of integration. However the internally used web services can be somewhat cryptic, so we have “wrapped” them to make them easier to use for the most common functions. If there are additional services you think we could provide via our exposed web services, please let us know by dropping us a note using our Customer Success Portal at www.innovativesystems.com\support.
The general idea behind the FinScan web services is to allow a calling application to request a compliance check on an individual or company. An example would be an on line banking application making a call to FinScan to check a new customer during their on-boarding process to ensure they are not on a Sanction or PEP’s list. The actual level of look up your call will execute depends on the Compliance Lists you elect to include in your system set up. For the SandBox application we provide to help you become comfortable with the web services, we use very simple and freely available Sanction files from the US and UK governments.
In the near future, we will be updating this page with information on a new set of web services optimized around the screening of payments. This will include checks on not only the sender and recipients names, but also country/currency combinations and payment amounts over time. The input data set for these new web services is built around the SWIFT/ISO 15022 standard.
The main function within the Wrapper is SLLookup. SLLookup screens the supplied Client Record against the selected Compliance List(s). It ensures that a record is searched with any matches that have not been previously reviewed (following the configurable set of change rules) to Review. If a record has been previously reviewed and were marked as SAFE or CONFIRMED HIT this value is returned (assuming a unique and permanent Client ID is used for each customer record).
The FinScan Wrapper is designed to be called from an existing process to screen a Client Record against a defined set of Compliance List(s) and returns a PASS/FAIL/PENDING result to the calling process. This result is then used to determine if the person/company is Safe (PASS), is not Safe (FAIL) or requires manual review (PENDING).
IMPORTANT: The FinScan Wrapper’s SLLookup function operates based on information for a single individual or organization and address. For multiple names (e.g., an individual name and an organization name), a separate call is required for each name or the SLLookupMulti function must be used.
Business users should be notified of the need for manual review for any name screens that receive a PENDING response from the FinScan Wrapper. This can be done after each screen or at the end of the client batch process. An email can also be sent that includes details of the pending screening that require remediation within the FinScan Case Management Tool.
Business users need to log into the FinScan Case Management Tool to review PENDING records. Users will use the Review component within the Case Management Tool in the same way they access the results of the batch to remediate the PENDING records. The matches associated with screenings can be identified in FinScan using the specific customer IDs and client sources.
When a Pending result is returned, the calling application must either wait for notification from the business users that the review has been completed or they can poll the status of the client’s matches by calling one of the two functions:
Calling either of these functions using the same Client ID that was used for the initial search will return the current status of the client’s matches without performing another search. The caller can continue calling this function until the review has been completed, in which case a PASS or FAIL status will be returned. The benefit of using SLLookup to poll the status is that you will not have to perform additional coding since the caller is already using that function.
Using the SLLookup function with the skipSearch parameter set to Yes or the SLGetStatus function will not perform a Search so they will not be included in the call volumes used to calculate billings.
Follow these links to see the details needed to call the web service
and access example source code:
REST SLLookup | Example Code C# | Example Code Python | Example Code Java
SOAP SLLookup | Example Code C# | Example Code Python | Example Code Java
SLLookup Multi performs the same function as SLLookup but instead accepts an array of separate names/sources/lists and returns an array of results as well as a summary of results. Up to eight records can be screened in one call using SLLookupMulti.
SLGetStatus returns the status of a Client record (PASS/PENDING/FAIL) without performing a screening or modifying the record. It also ensures that the change rules are applied and that any records previously marked SAFE and CONFIRMED HIT retain their status.
SLUpdateClientId modifies a record’s Client ID within FinScan (as well as optionally most other Client fields) without screening the record.
SLUpdateClient modifies the entire Client record without screening the record.
SLPing validates that FinScan Web Services are responding and returns both the FinScan Web Services and the Wrapper Versions
The Sandbox provides you an easy way to get started to learn how the web services work, however if you want to connect to your own instance of Finscan (Hosted or OnPremise) there are a few key things you need to understand.
FinScan structures its security in three levels. When you make a web services call you need to understand these levels as you need to know “where” you are accessing FinScan as this information is needed as part of the calling parameters. Within a physical instance of FinScan, there are three components to your “point of entry” (there “where” part mentioned above).
With an understanding of the Security structure and the API’s themselves, you are ready to connect your application to FinScan via Web Services. To determine your web service access point URL you need to:
The SandBox test system has been set up to allow easy access to a test system for you to check out the operation of the FinScan web API. This system is set up to only use the OFC Sanctions list. Any name on this list will return a match. The information below can be used to access this test system. If you have any questions, you can submit them via our Customer Support portal at www.innovativesystems.com\support.
REST API URL:
SOAP API URL: https://isi-api-doc.azurewebsites.net/LSTServicesLookupSOAP/LSTServicesLookup.asmx
Sample names on the OFAC List
1. Robert Mugabe (person)
2. Manuel Diaz (person)
3. Mohammad Hossein Dajmar (person)
4. Noor Plantation Investments LLC (organization)
FinScan does not use a session based token system for authentication. Each and every web call you make will include the security credentials of Organization, Application, UserID and Password as parameters. These items are defined in more detail in the Getting Started section.
If you are using the SandBox we have already configured it to support web service access. However if you are connecting to your own instance of FinScan (OnPremise or Hosted) you may have to configure a few parameters to allow web services to be supported. If this was part of your original system configuration, your Professional Services consultant should have already set things up. There are three things you need to complete; setting up a user account that the web services can use to connect and then ensuring that account has the proper access rights. This is detailed below
The username used in the Web Service calls must have its Web Service Identity set to “[Self]”. To do this
To assign user rights:
In order to keep the Search response times down, there is a setting to limit the number of results returned by a Full Name Search. To access the “FinScan Full Name Maximum Records to Return” setting:
If the number of matches found is greater than the Maximum Records to Return setting, only the Maximum number of matches will be returned and the count of the number of records over the Maximum will be returned in the “notReturned” Field.
As a result, the “notReturned” field should be checked after each call. If the “notReturned” field value is greater than zero, that record should be Searched manually within the FinScan Case Management Tool and the full results sent to Review to be sure that no potential matches are missed.
IMPORTANT: The Wrapper will automatically return a PENDING response whenever the notReturned field is greater than 0 (unless there are Confirmed Hits in which case it will return FAIL).
Any Compliance Lists/Categories selected as Mandatory within the Case Management Tool will always be used in Web Service Lookups. Additional Lists/Categories can be added to the Lookup using the complianceLists field but Mandatory Lists/Categories cannot be disabled. The Search Mandatory options can be accessed by:
Web Services use HTTP response status codes to indicate the status of a request. The type of status is separated into ranges. 200’s indicate success, 400’s indicate a client error (typically due to the content or structure of the request), and 500’s indicate a server error. 500 errors are rare, and should be handled by contacting FinScan customer support. Additional information on HTTP errors can be found on the web at Wikipedia and others.
For the FinScan Wrapper, there are also specific errors returned for different conditions, such as invalid credentials, missing fields, etc. Here are some troubleshooting tips for the more common FinScan/Wrapper errors:
Authentication Error (SSQSearchQueryGet):
Authentication Error (SSQSearch):
Authentication Error (SCQReviewClientRecordGet):
Error retrieving FinScan Service URL from Web.Config. Please add Key value to the web.config file on the server where the wrapper is deployed in the AppSettings section similar to: '< add key="WebServiceURL" value="http://localhost/finscan3xxx" />'
There needs to be an Application Key added to the web.config that tells the Wrapper where to find the FinScan Web Services. The name of the Key is “WebServicesURL” and needs to contain the base URL of the FinScan Web Site.
ERROR Initializing Search Type: Unknown Search Type Encountered
An Invalid Search Type was entered, the valid types are:
Lookup ERROR (Initialization): Request Object Not Initialized.
The Request Object field was Empty/Null/Nothing.
Lookup ERROR (Initialization): Organization Not Initialized.
The “organizationName” field was Empty/Null/Nothing.
Lookup ERROR (Initialization): Client Application ID Not Initialized.
The “applicationId” field was Empty/Null/Nothing.
Lookup ERROR (Initialization): Client ID Not Initialized.
The “clientId” field was Empty/Null/Nothing.
Lookup ERROR (Initialization): Specific Element Not Initialized.
The “specificElement” field was Empty/Null/Nothing (for Specific Element Search Types only).
Lookup ERROR (Initialization): Name Line Not Initialized.
The “nameLine” field was Empty/Null/Nothing (for Individual/Organization/Individual_Both/Organization_Both Search Types only)
Lookup ERROR (SSQSearch):
Lookup ERROR (UserField SSQSearch ID-#):
Lookup ERROR (SRLSTReviewPairGet):
Lookup ERROR (SSQSearchSendToReview):
Lookup ERROR (CLSTClientSearch):
Lookup ERROR (CLSTClientGet):
Lookup ERROR (CLSTClientUpdate):
Lookup ERROR (SCQClientAdd):
GetStatus ERROR (CLSTClientSearch):
Error in SSQSearchQueryGet(): Message: No Response
Error in SSQSearchQueryGet(): Message: _MESSAGE_
ERROR Processing Records, see individual records for details
Error encountered calling SLLookup for client ID #
For the remaining Errors, check the “message” Field for more details and contact FinScan customer support for additional help.
For Exceptions, check the “message” Field for more details and contact FinScan customer support for additional help.
1. Will the implementation allow for a single WS call to FinScan to perform the “search” and “send to review request”? Or do we still need to make two calls via “SSQSearch()” and “SSQSearchSendToReviewUpdate”?
A. The implementation requires only one “search” request. A “send to review” request will automatically be generated for each potential match found (as long as the “sendToReview” option is set to “Yes.”)
2. How do we add the client data (with “prospect ID”) in case no potential matches are returned from FinScan (i.e., the client has PASSED)? Will the above calls be able to take care of that or do we need to make separate calls like “SCQClientUpdate()”?
A. If no potential matches are returned, there is no need to add client data within FinScan at this stage. An audit log is created from each search that will indicate if a match occurred or no match was found. Along with the fact that no potential matches were found, the client record can be added to the FinScan database through the batch files.
3. What if one or more potential matches were found?
A. You should probably fail the client and let the back office team review and analyze the match(s).
4. Does the original SSQSearch() take any ID where we can send the “prospect ID”? Is “client ID” the field which will take in “prospect ID”?
A. Yes. “Client ID” is the field to populate with “prospect ID”. This is the unique reference used by FinScan. Please note, the Client ID can be modified using one of the Update Client functions. That way, if a Prospect only has a Temporary ID when the Search is performed, the generated Client Record can be updated with the permanent Client ID if the Prospect becomes a Client.
5. Do you store any record passed through the “SSQSearch()” or is it only stored when “SSQSearchSendToReviewUpdate” or “SCQClientUpdate()” is called?
A. Records are stored for each of the calls in different tables within FinScan. The search is maintained in an audit log table with details of the search and its results. “Send to review” and “client update” populates the client table, which will be loaded via the batch process.
6. What is contained in the audit log?
A. For all searches. the audit log table contains all of the details passed via the search Web Service (which can include name, address, etc., as well as the prospect ID and any notes). These details can be viewed by users in the FinScan Review Tool or extracted in a report.
7. Does the Wrapper support all View modes?
A. Yes, the Wrapper supports all View modes.
8. Will the Wrapper return pairs only for the source used in a search?
A. Yes. The Wrapper filters pair results based on the requested source.
9. Does Search Type override Gender?
A. Yes. If Organization is selected as the Search Type, the male/female gender option is ignored.
1. Are the Address Lines required in the Request Object?
A. No, the Address Lines are not required, but they may help to produce better matching results and will provide more information within the Case Management Tool.
2. Are the Compliance List and Category information required in the Request Object?
A. No, if you pass in an empty Compliance List, the system will use the default Mandatory Compliance Lists and Categories for that source. If no Lists/Categories are set as Mandatory and the List Category is not provided in the Request, then no records will be searched, no Pairs will be found, and a PASS will be returned.
3. When would I want to set updateUserFields to “Yes” or “No”?
A. A list of valid countries can be found here
5. How should my date of birth be formatted?
6. Why am I getting the same results back for two or more different names I've searched?
A. Ensure you are specifying a different Client-ID for each name being searched.
1. What should I do if I get an error back from the call to the FinScan Wrapper?
A. Once a connection to the FinScan Service has been established, there will be very few ERROR values returned from the service. Typical Error responses are documented here. Since most of these are Timeouts due to Internet traffic, you should retry the call to the FinScan Wrapper three to five times. If you receive an ERROR status back from the call each of these times for the same record, check the Message field since that will have additional information regarding the problem. If that is not enough information for you to resolve the problem, contact Innovative Systems Support via our Support page at www.innovativesystems.com\support .
2. Will the service ever return PASS when “notReturned” is greater than 0?
A. No, the service will return a PENDING (or FAIL if there is at least one CONFIRMED HIT) whenever notReturned is greater than 0.
3. Please explain the differences between the following return responses: PASS, PENDING, FAIL, ERROR, and UNINITIALIZED.