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 the World Compliance Database 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.
POST BODY
{
"type": "individual / business (delete one)",
"name": "string",
"screeningThreshold": integer
"countryCode": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dateOfBirth": "string",
"nationalId": "string",
"gender": "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. The parameter 'name' is a compulsory parameter for 'type': 'business' 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, NOTE: If using 'individual' the API will return less noisy results by using the optional parameters 'firstName', 'middleName', and 'lastName' rather than this parameter. |
| "screeningThreshold" | Can only use the following integers: 85, 90, 95, 100 All other numbers will return an error. |
| ''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 |
| ''dateOfBirth'' | Individual Only: Date of Birth |
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.
IMPORTANT DEFINITION:
'alertsCount' in creating an Investigation is equal to the number of the results you have in that search.
More details around this object in the SCHEDULE section as it has another definition beyond the initial search.
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:
"results": [
{
"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 and will be ready for review.
Each of the results/alerts will have an Id. The Id field is also known as an investigationRecord, this 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 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 the database screens 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 please contact your account manager who will be able to help you further.
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.).
NOTE: Any Id's that are not passed into the investigation at this point will be deemed as default a 'falsePositive'. These results will not be obtainable again.
If a result has the potential to be a 'True Match' add it to the investigation. This can be changed later with a PUT call to update the record to a 'falsePositive' if it is no longer required.
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 MUST submit an empty array as confirmation that no InvestigationRecords are matches. This allows for the process to close. 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 branded PDF that shows the full report for the selected entities. This report will include search criteria used, user, time/date stamp and full 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 grouping 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 means 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.
Scheduling only sets up the frequency to check an investigation on a daily basis. A user will only get a notification via email if a new alert is detected.
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",
"screeningThreshold": 85
}The information needed to create a schedule (or add something to monitoring) is minimal. See the parameters needed below:
| Parameter | Explanation |
| ''investigationId'' | The ID created when you created the initial investigation |
| ''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 'alertsCount' in this section refers to unprocessed alerts.
The 'currentAlert' is only there if there is actually an open alert, otherwise this response will be missing.
NOTE:
'alertsCount' is the number of hits that have been found on the current open alert - it is NOT a cumulative count.
Check the 'currentAlert' property for new alerts - this will then help to call the results back.
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. Scheduled Investigations will be screened daily unless there is a current unprocessed open alert against it. It will not be screened again until this alert has been processed. 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 to investigionRecords, or submit an empty array to the /protect/investigations/{investigationId}/records.
Important Note: Hard requirements - If there are no True Matches you have to pass the empty array to confirm and close the process on the those results.
Due to the fact that none of the alerts maybe true matches in this instance, does not mean that a future alert will not be. Passing an empty array just actions the current unprocessed alerts to 'False Positive'.
It is a requirement that a decision is made on the new Alerts - you cannot leave them unprocessed.
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": Record Accepted "alert.rejected": Record Discounted "alert.received": Alert Received "investigation.accepted": Relevant Result Selected "investigation.created": Search Conducted "investigation.rejected": Result Rejected "investigation.removed": Investigation Removed "investigation.file_downloaded": Results Report Generated "investigation.risk_assigned": Risk Rating Change "investigation.record_removed": Record Removed "investigation.note_removed": Investigation Note Removed "investigation.assigned_to": Assigned User "investigation.status": "Investigation Status Changed "idv.file_downloaded": Idv Report Generated "idv.gdc_search": Idv Search Conducted "note.created": Note Created "profile.created": Profile Created "profile.added": Search Added to Profile "profile.updated": Profile Updated "schedule.created": Search Added To Monitoring "schedule.recharged": Search recharged for Monitoring "schedule.disabled": Search disabled for Monitoring "schedule.deleted": Search deleted from Monitoring "schedule.removed": Search Removed From Monitoring "schedule.updated": Search Updated in Monitoring "report.monitoring.requested": Monitoring Report Requested "report.monitoring.submitted": Monitoring Report Submitted "report.monitoring.completed": Monitoring Report Completed "report.monitoring.failed": Monitoring Report Failed
|
| ''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"
}Batch Upload
Returns Batch Upload Template
GET https://connect.creditsafe.com/v1/protect/batchUploads/templates/{type}GET https://connect.sandbox.creditsafe.com/v1/protect/batchUploads/templates/{type}The only value that is usable right now is `template`. This is required in the path and provides a link to produce the header list required in csv format.
Batch Upload File
POST https://connect.creditsafe.com/v1/protect/batchUploads
POST https://connect.sandbox.creditsafe.com/v1/protect/batchUploads
The header 'type' requires either 'individual' or 'business' to be determined on each line when submitting a batch CSV file.
After using this POST call to upload a file, a user will be required to call either of the following two options:
- GET: Returns Batch Uploads
- GET: Returns Batch Uploads by Id
This is to check the status of the file, the possible ENUM values are displayed in the table below
| Response | Value |
| status | inProgress completed partiallyCompleted failed |
Returns Batch Uploads
GET https://connect.creditsafe.com/v1/protect/batchUploads
GET https://connect.sandbox.creditsafe.com/v1/protect/batchUploads
This endpoint will allow a user to return all the batch upload files submitted to the server. If there is more than one file is will return the items in an array format.
This can be used to see the current 'status' of a file upload.
Returns Batch Uploads by ID
GET https://connect.creditsafe.com/v1/protect/batchUploads/{batchUploadId}GET https://connect.sandbox.creditsafe.com/v1/protect/batchUploads/{batchUploadId}This endpoint has the same capability as the one above. This endpoint will only call the ID of the specified batch upload.
This can also be used to check the 'status' of the batch file.
Returns Error File Link
GET https://connect.creditsafe.com/v1/protect/batchUploads/{batchUploadId}/errorFileGET https://connect.sandbox.creditsafe.com/v1/protect/batchUploads/{batchUploadId}/errorFileIf the status of a file returns as 'failed' this endpoint can be called the pull a file back to detail the error.