FinScan Web Services API
Getting Started Guide.
Getting Started Guide.
Integrating compliance workflows 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.
This allows for efficient and safe customer onboarding from all entry points and protects your organization on all fronts with real-time screening. Plus, FinScan’s advanced and efficient 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 configured 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:
https://<servername>.com/<directory>/LSTServicesLookup.asmx
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.
The Hosted FinScan Test Sites are being updated to FinScan v6.12. As a result, the new v6.12.0 Native Wrapper has been released which has a different footprint from the previous Wrappers (request/response) and will be the Supported FinScan Wrapper going forward. v6.12.0 added:
v6.8.1 added:
v6.8.0 added:
v6.7.0 added:
Please note, removing the Custom Status fields from the request in v6.7 means that clients will need to update their Custom Statuses within the FinScan web application to be the appropriate value (Safe/Confirmed Hit) for them to be handled properly within the Wrapper. Otherwise, the Wrapper will return PENDING for those statuses. This can be set in the "Search & Review" section within your Organization Settings. Select "Status Definition" and set the "Final Status Designation" field for your custom Statuses to be "Safe" or "Confirmed Hit"
v6.6.3 added:
v6.6.2 added:
v6.6.1 added:
Additional changes include a listReviewLink field added to the SLComplianceRecord Class in order to return a direct link to the List Review Page for that Pair and added support for standardizing the Specific Element field the same way a User Field is standardized using the userFieldsCountry array. The value "21" in the userFieldsCountry array will now indicate the Specific Element field is to be standardized (now have 20 User Fields).
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.
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.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLLookupMulti
SOAP SLLookupMulti
Please note, the SLLookupMulti is designed to be used for a small group of related clients to get an overall PASS/PENDING/FAIL response in addition to the individual PASS/PENDING/FAIL statuses. It was not designed to be used for multiple unrelated screenings in a single call. Also, since the SLLookupMulti simply calls SLLookup for each client provided (single-threaded), it would likely be faster to make individual multi-threaded SLLookup calls.
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.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGetStatus
SOAP SLGetStatus
SLUpdateClientId modifies a record’s Client ID within FinScan (as well as optionally most other Client fields) without screening the record.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUpdateClientId
SOAP SLUpdateClientId
SLUpdateClient modifies the entire Client record without screening the record.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUpdateClient
SOAP SLUpdateClient
SLPing validates that FinScan Web Services are responding and returns both the FinScan Web Services and the Wrapper Versions
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLPing
SOAP SLPing
SLRescreen allows you to rescreen an existing Client record using only the Client ID/Application ID. It screens the Client, and returns the current Status of all matches.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLRescreen
SOAP SLRescreen
SLImageLookup accepts an Image File or Files (Front/Back) of an ID such as a Drivers License or Passport as a JPEG, calls the Acuant ID Validation Service, then loads the Image and the information retrieved from the Image into FinScan and performs a screening.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLImageLookup
SOAP SLImageLookup
SLUpdatePairs takes the information for the matches returned in a call to SLLookup or SLGetStatus (the List Profile Keys) and updates their Status/Reason/Comments.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUpdatePairs
SOAP SLUpdatePairs
SLPayment takes generic payment information (such as Person/Bank name, address, country, account, currency), processes the information, and returns the status and result of the screening.
Follow these links to see the details needed to call the current version of the web service and access example source code:
REST SLPayment
SOAP SLPayment
SLGetUpdatedClients returns Clients with Matches that have been updated within the specified Time Period.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGetUpdatedClients
SOAP SLGetUpdatedClients
SLGetUpdatedTransactions returns Transactions with Matches that have been updated within the specified Time Period.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGetUpdatedTransactions
SOAP SLGetUpdatedTransactions
SLUpdatePaymentExceptions updates Matches within Transactions (Countries/Currency/etc.) that have been sent to Review.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUpdatePaymentExceptions
SOAP SLUpdatePaymentExceptions
SLPaymentAPI screens a Payment Transaction.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLPaymentAPI
SOAP SLPaymentAPI
SLDeleteClient deletes a Client record from FinScan.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLDeleteClient
SOAP SLDeleteClient
SLUserAdd adds a new User to a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUserAdd
SOAP SLUserAdd
SLUserUpdate updates a User within a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUserUpdate
SOAP SLUserUpdate
SLLookupMultiNetwork adds the functionality for creating/updating a Client Network to the SLLookupMulti function.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLLookupMultiNetwork
SOAP SLLookupMultiNetwork
SLNetworkCreate creates a Client Network within a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLNetworkCreate
SOAP SLNetworkCreate
SLNetworkDelete deletes a Client Network within a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLNetworkDelete
SOAP SLNetworkDelete
SLNetworkMemberAdd adds a Client to an existing Network within a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLNetworkMemberAdd
SOAP SLNetworkMemberAdd
SLNetworkMemberRemove removes a Client from an existing Network within a FinScan Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLNetworkMemberRemove
SOAP SLNetworkMemberRemove
SLGroupCreate creates a new Group with the options and Users specified in the request.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGroupCreate
SOAP SLGroupCreate
SLGroupUpdate updates an existing Group with the Users specified in the request.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGroupUpdate
SOAP SLGroupUpdate
SLListRecordAdd adds a new Record to a Custom List.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLListRecordAdd
SOAP SLListRecordAdd
SLListRecordUpdate updates an existing Record within a Custom List.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLListRecordUpdate
SOAP SLListRecordUpdate
SLListRecordDelete removes an existing List Record from a Custom List.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLListRecordDelete
SOAP SLListRecordDelete
SLClientGet Retrieves the details for a Client Record.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLClientGet
SOAP SLClientGet
SLGroupDelete Deletes an existing Group from an Organization.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGroupDelete
SOAP SLGroupDelete
SLPaymentAPICancel Sets a Payment (Payment API only) as Cancelled.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLPaymentAPICancel
SOAP SLPaymentAPICancel
SLUserGet Retrieves a User's Details, including Status, Email, Phone, Groups, Language, etc.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLUserGet
SOAP SLUserGet
SLGroupGet Retrieves a Group's Details, including Rights, Users, Welcome Message, etc.
Follow these links to see the details needed to call the current version of the web service
and access example source code:
REST SLGroupGet
SOAP SLGroupGet
SLAdmin Internal function.
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:
https://isi-api-doc.azurewebsites.net/LSTServicesLookupREST
SOAP API URL: https://isi-api-doc.azurewebsites.net/LSTServicesLookupSOAP/LSTServicesLookup.asmx
Also, the Payment function has now been enabled for the SandBox (SLPayment). The Credentials for this call are as follows:
The FinScan Web Services 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
To use the FinScan Wrapper, clients must have the following features included in their License Key:
Please contact your Sales/Account Manager if you are not licensed for these features.
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):
Message: **TRANSLATION MISSING**
ERROR: SLLookup (User Fields):
Unable to retrieve User Field Definitions
Authentication Error (SSQSearch):
Authentication Error (SCQReviewClientRecordGet):
Rights:
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 (SRLSTReviewPairGet):
GetStatus ERROR:
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.
EXCEPTIONS:
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. What fields are required?
A. Depending on the entry point called, the required fields will vary. However, the following are the minimum required fields for the most often asked for calls:
Please note, any of the remaining string fields will be processed as blank and all other fields will use their default (first) value listed in their description so all Yes/No options will default to No and SLLookup will default to Male Individual searches and will neither Send to Review nor create new Client records.
2. 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.
3. 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.
4. When would I want to set updateUserFields to “Yes” or “No”?
A.
A. A list of valid countries can be found here
5. How should my date of birth be formatted?
A. YYYYMMDD
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.
Copyright © 2007-2023 by Innovative Systems, Inc. All rights reserved. FinScan™ is a trademark of Innovative Systems, Inc.