TABLE OF CONTENTS
Introduction
Each day your organisation makes decisions on who to do business with, Protect delivers the intelligence you need to make decisions quickly and grow business relationships with confidence. Powered by real-time data from over 30,000 trusted and official sources, Protect performs a fast and comprehensive risk assessment on business relationships anywhere in the world. We enable you to confidently screen new and existing businesses relationships in as little as three clicks, to protect your business from the threat of white-collar crime, money laundering and reputational damage.
Throughout this guide we will refer back to the swagger documentation which can be found HERE.
Investigations
An investigation is the terminology used within Protect for a search. For example by searching for 'Donald J Trump' is the same as 'Creating an Investigation' for 'Donald J Trump.
Create A New Investigation
Live
POST https://connect.creditsafe.com/v1/protect/investigationsSandbox
POST https://connect.sandbox.creditsafe.com/v1/protect/investigationsInvestigations are created against Businesses or Individuals, but you also need to decide which additional parameters you have available to base your Investigation on. This is typically a Name and an Address.
Currently the Protect API mirrors the scoring method of LexisNexis World Compliance meaning that scoring is based solely on the report name. This means if you were to pass through 'Donald J Trump' or 'Donald J Trump, USA' they would return the same results.
For audit purposes you have the ability to pass through other search parameters in the POST body which are listed below:
POST BODY
{
"type": "individual / business (delete one)",
"name": "string",
"houseNo": "string",
"street": "string",
"province": "string",
"city": "string",
"postCode": "string",
"countryCode": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"generation": "string",
"dateOfBirth": "string",
"nationalId": "string",
"citizenship": "string",
"phoneNo": "string"
}| Parameter | Explanation |
| ''type'' | All reports are split into two main categories 'Individual' and 'Business'. This is a compulsory field which must be used in an investigation. Note: Individual relates to individuals Business relates to businesses and organisations e.g political parties and terrorist groups |
| ''name'' | The full or partial business or individual name |
| ''street'' | The street address of the individual or business. Note: Building names or number can be included in the field |
| ''province'' | Province or State |
| ''city'' | City |
| ''postCode'' | Post/Zip Code |
| ''countryCode'' | Two letter country code. List can be found HERE |
| ''firstName'' | Individual Only: To be used instead of ''name'' field should the user want to split out the name into first, middle, last |
| ''middleName'' | Individual Only: To be used instead of ''name'' field should the user want to split out the name into first, middle, last |
| ''lastName'' | Individual Only: To be used instead of ''name'' field should the user want to split out the name into first, middle, last |
| ''generation'' | Individual Only: Example JR, SNR, III. Usually associated with American names |
| ''dateOfBirth'' | Individual Only: Date of Birth |
| ''nationalID'' | Individual Only: National ID Number |
| ''citizenship'' | Individual Only: Nationality |
| ''phoneNo'' | Phone Number |
Managing Results
Investigation Results
It is important to keep in mind that unlike Credit Reports, the majority of the time a search result is not expected. The existence of any Business or Individual outside of Protect does not mean there must be a corresponding Investigation search result for that entity within Protect. You are searching against finite lists and sources from the World Compliance Database. These are exclusively populated by Businesses and Individuals that meet a strict criteria e.g. They possess PEPs, SEOs, Sanctions.
For example if you were to create an investigation for 'Creditsafe' we would expect (and hope!) there would be no results
Managing False Positives
This section will give guidance on where to find the relevant information to make a decision in the event there are results returned to review.
Each result will contain some or all of the fields listed below:
[
{
"id": 0,
"entityId": "string",
"matchScore": 0,
"sourceDate": "string",
"dateListed": "string",
"name": "string",
"fullName": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"reasonListed": "string",
"entityType": "string",
"dateOfBirth": "string",
"generation": "string",
"gender": "string",
"occupation": "string",
"placeOfBirth": "string",
"hasAdverseMedia": true,
"otherNames": [
"string"
],
"addresses": [
{
"street": "string",
"city": "string",
"province": "string",
"postalCode": "string",
"country": "string"
}
],
"comments": [
"string"
],
"sources": [
"string"
]
}
]This particular example just lists one result. You will likely have multiple results for each search. ''alertsCount'' will give the number of potential matches that have satisfied your search criteria.
Each of the results/alerts will have an Id. The Id field is also known as an InvestigationRecord, and will be important in managing True Positives / False Positives in the next section. It is important to make note of the Id field of relevant results because this will be the value required to mark a result as a 'true match'.
| Response | Explanation |
| ''id'' | This is unique ID number relating to the LexisNexis World Compliance report. It is also known as the InvestigationRecord which is used in the next section for Managing Results. |
| ''matchScore'' | This is a percentage based score depicting how accurate the search parameters relate to the report name |
| ''sourceDate'' | This is the date the report was last updated. (please keep in mind LexisNexis screen over 35,000 sources so if a date appears a long time ago , the data isn't out of date, it just means that there has been no changes to the information since that date) |
| ''dateListed'' | The date the report was originally created |
| ''name'' | Report Name |
| ''fullName'' | Individual Only: Segregated Name Parts |
| ''middleName'' | Individual Only: Segregated Name Parts |
| ''lastName'' | Individual Only: Segregated Name Parts |
| ''reasonListed'' | The World Compliance Database is split into 132 different categories, each category represents a reason that a report would exist. Full list of categories can be found here: |
| ''entityType'' | Business or Individual |
| ''dateOfBirth'' | Individual Only: Date of Birth |
| ''generation'' | Individual Only: Example JR, SNR, III. Usually associated with American names |
| ''gender'' | Individual Only: Male or Female |
| ''occupation'' | Individual Only: Position |
| ''placeOfBirth'' | Individual Only: Place of Birth |
| ''hasAdverseMedia'' | Is Adverse Media available for this Business or Individual? True/False |
| ''otherNames'' | Known AKAs and Aliases |
| ''addresses'' | Addresses |
| ''comments'' | Often the most important part of the report. This outlines the details of the reason listed and provides context to any crimes that may have been committed |
| ''sources'' | The links to the adverse media sources directly |
Making A Decision
Creditsafe cannot advise on what constitutes a pass or fail, this would have to be dictated by your internal onboarding policy. What we can do however, is make getting to the relevant information needed as simple as possible.
The full data guide is attached to this article and if you have any specific data queries you can speak to the LexisNexis World Compliance Research Team directly on Research@risk.lexisnexis.com
Finding A Match
Swagger
Once you find a report or reports to believe match your search criteria you can add that match to an investigation. You do this by using the following endpoint and passing through the investigation Id and the InvesigationRecord Ids found in your search. (The InvestigationRecord Ids are the Id fields of each result in your initial search investigation. If you have an investigation of three hits, and only two are relevant, you would take the Id/InvestigaitonRecords of the two relevant results from the Investigation creation response, and leave the remaining Id.).
POST https://connect.creditsafe.com/v1/protect/investigations/{investigationId}/recordsPOST https://connect.sandbox.creditsafe.com/v1/protect/investigations/{investigationId}/recordsPOST Body
{
"recordIds":[
{{investigationResultId}}
]
}In the API Body, you include the records that are relevant (or true matches). You must leave out the InvestigationRecords that are false positives. If no results are true matches, then you need to submit an empty array as confirmation that no InvestigationRecords are matches. See below example:
{
"recordIds":[
]
}Creating A PDF Report
Once you have selected matches for your investigation you have the ability to retrieve the full list of matches as a PDF report. The following endpoint creates a LexisNexis branded PDF that shows the full report for the selected entities. This report will include search criteria used, user, time/date stamp and full LexisNexis World Compliance Report. It is recommended to call this endpoint before adding InvestigationRecords to an Investigation, as only non-processed alerts populate the PDF. The following endpoint will generate the PDF file in a repository (currently s3) and return an endpoint pre-prepared for you to retrieve it.
POST https://connect.creditsafe.com/v1/protect/investigations/{investigationId}/filePOST https://connect.sandbox.creditsafe.com/v1/protect/investigations/{investigationId}/fileProfiles
Adding To Profile
'Profiles' within Protect are a way of group searches together. For example:
If I was to onboard Creditsafe, I may create and investigation for Creditsafe but also create investigations for Safe Information Group (our parent) and Cato Syversen (our CEO).
You can create a Profile by using the following endpoint:
POST https://connect.creditsafe.com/v1/protect/profilesPOST https://connect.sandbox.creditsafe.com/v1/protect/profilesPOST Body
{
"name": "string"
}Profile names should be unique for audit purposes.
After the Profile has been created, you can then add Investigations to it (in the above example, we can add the three separate investigations to the "Creditsafe" Profile.
Please note, each individual Investigation still requires its own Schedule to be monitored, even if they are grouped together in a Profile.
PUT https://connect.creditsafe.com/v1/protect/profiles/{profileId}/investigations/{investigationId}PUT https://connect.sandbox.creditsafe.com/v1/protect/profiles/{profileId}/investigations/{investigationId}Viewing a Profile
Should you want to see what you have stored in a specific profile you can you use the following endpoint to retrieve them:
GET https://connect.creditsafe.com/v1/protect/profiles/{profileId}/investigationsGET https://connect.sandbox.creditsafe.com/v1/protect/profiles/{profileId}/investigationsSchedules (Monitoring)
Creating a Schedule
Just because someone's not on a sanctions list today doesn't mean they wont' be tomorrow. By monitoring your investigations Protect makes sure you never miss a change.
A 'Schedule' within Protect just mean ongoing monitoring. A Schedule has a 1:1 relationship with an Investigation.
Investigations that are scheduled will automatically re-screen your initial search criteria on a nightly basis allowing you to review any new alerts each day.
You can create a schedule by using the following endpoint:
POST https://connect.creditsafe.com/v1/protect/scheduleshttps://connect.sandbox.creditsafe.com/v1/protect/schedules{
"investigationId": "string",
"frequency": "daily",
"screeningThreshold": 85
}The information needed to create a schedule (or add something to monitoring) is minimal. See the parameters needed below:
| Parameter | Explanation |
| ''investigationiId'' | The ID created when you created the initial investigation |
| ''frequency'' | "Daily" is recommended. |
| ''screeningThreshold'' | The match score you will be alerted above. This relates to ''matchScore'' in the investigation results. For example if I was to chose 85, I would be alerted to any matches with a match score or higher. 90, match score of 90 or higher etc This is used mainly to reduce false positives as the higher the number the less results you will have returned. Options: 85/90/95/100 85 Recommended |
Getting Updates from your Schedules
After you have set an Investigation to a Schedule, the Get Investigation endpoint allows you to query which Investigations have new alerts by using the alertsCount parameter.
The 'Alert' system in Protect works in a very similar way to the Finding A Match process. This is because Protect is researching the same criteria on a scheduled basis to find changes in your investigation.
How often you choose to check the Investigation has Alerts (therefore new results) is up to you. As new results will be added daily, it is advised to retrieve the results at the same frequency (once per day) to avoid redundancy.
GET https://connect.creditsafe.com/v1/protect/investigationsGET https://connect.sandbox.creditsafe.com/v1/protect/investigations"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"userId": 0,
"customerId": 0,
"query": {},
"scheduleId": "string",
"scheduledOn": "2019-08-24T14:15:22Z",
"profileId": "string",
"profileName": "string",
"alertCreatedAt": "2019-08-24T14:15:22Z",
"alertsCount": 1
}| Parameter | Explanation |
| ''alertsCount'' | Investigations with "Alerts greater or equal to the value provided". i.e. If the value 1 is provided, it will return all investigations with one or more unremediated alerts. |
Making A Decision on Schedule Alerts
Investigations that have new Alerts are managed in an identical way to the initial results of an Investigation. Either approve the new InvestigationRecord as True Matches, by adding an array of the Investigation's investigionRecords, or submit an empty array to the /protect/investigations/{investigationId}/records
See Managing Results / Managing False Positives for more information.
Delete A Schedule From An Investigation (Stop Monitoring an Investigation)
Investigations will be monitored until you remove them from schedule. If you want to remove an investigation from the schedule use the following endpoint
DELETE https://connect.creditsafe.com/v1/protect/schedules/{scheduleId}DELETE https://connect.sandbox.creditsafe.com/v1/protect/schedules/{scheduleId}Audit Log
Retrieve Protect Audit Log
When performing Business and Individual Screening, providing proof that the necessary checks and actions were performed correctly may be vital for adhering to local regulation and laws.
We log each action you perform against the Protect Endpoints in our Audit Log for you to keep an Audit Trail.
The 'Audit Log' (Audit Trail) can be found at the endpoint:
GET https://connect.creditsafe.com/v1/protect/audits
GET https://connect.sandbox.creditsafe.com/v1/protect/audits
To retrieve the Audit Log the data required is:
| Parameter | Explanation |
| ''page'' | Starting page number (Default 1) |
| ''pageSize'' | Number of items to return per Page. |
| ''type'' | The type of event listed in the Audit Log e.g ''alert accepted'', ''alert rejected'' Full list of possible "alert.accepted" Alert accepted as match "alert.rejected" Alert rejected as match "alert.received" New alert created "profile.added" Investigation added to Profile "profile.created" New profile created "investigation.accepted" Investigation accepted as match "investigation.created" New investigation "investigation.file_downloaded" PDF report created "schedule.created" Investigation added to monitoring "schedule.removed"Investigation removed from monitoring |
| ''newerThan'' | Start date<date-time> |
| ''olderThan'' | End date <date-time> |
| ''profileId'' | The ID for the profile |
Export Audit Log File
This function allows you to export your Audit Log from Protect in a CSV format. The endpoint can be found here:
POST https://connect.creditsafe.com/v1/protect/auditsPOST https://connect.sandbox.creditsafe.com/v1/protect/audits{
"fileType": "csv"
}