Check Results - Summaries
The CheckEntityCheckResultObject has a number of summary sections that are available.
The entityProfileResults section (see above), provides a detailed overview of the results based off the recipe assigned to the entity. This is only present where entity profiles/recipes are in use (strongly recommended for all API users).
A still relevant, but being phased out section, is the checkSummary which is the pre-cursor to the above entityProfileResults. It’s still useful for those API users still running individual checks, rather than recipes.
And lastly, there is a collection of individual check summaries, one for each time the service has run the /entity/verify API endpoint in reverse chronological order.
Understanding CheckSummary results
The individual checkTypes are being phased out
Unless there is a specific reason to not do so, please move to using Entity Profiles, rather than running individual checks..
The following section details how to interpret the results of a /verify check on an entity.
Whenever a check is performed upon an entity, a summary record is returned as part of the response data. This is found in the checkSummary object and represents the sum total of information about this entity and all previous relevant checks.
If you’re just after the results of the latest check, look for the most recent summary record in the `checkSummaries` list.
As part of the primary summary object, there is an array of typed Key-Value Pairs called CheckResults.
In there, we will return any specific flags or data that we think might be useful for the developer to take immediate action on, rather than having to dig through the individual results.
The kvpKey is generally made up of 2 parts: <Level>.<Flag>
<Level> is designed to indicate the level of importance of the flag. Valid values are:
- Info - Flag is purely informational.
- Issue - Flag is highlighting something that’s a potential issue.
- Important - Flag is indicating something we feel is Important and requires potential intervention.
- Action - Flag indicates a recommended action.
- Fail.Reason - Why the entity is currently in a failed state.
- Review.Reason - Why the entity is currently marked as REFER.
<Flag> is the name of the flag and is generally self-explanatory (see notes below).
The kvpType is one of the enumerated KVP types found in our OpenAPI specification. We’ve translated that to a more readable form here.
Example check summaries
Biometrics
- Biometrics overall FAIL, with OCR and Document report as suspected, but photo comparison rejected:
- Biometrics overall FAIL, with all the reports as suspected:
- Biometrics overall REFER, with OCR report as suspected, but Document report and Photo comparison as clear:
Interpreting CheckSummary results
This method is being phased out
The following section details how to interpret the results of a /verify check on an entity when the checkType details are specified in full (rather than just using the “profile” option).
Unless there is a specific reason to not do so, please move to using Entity Profiles, rather than running individual checks..
Following on from the article about the contents of a checkSummary
The CheckSummary is formerly the main place to look to determine the current state of an entity,
(It still can be used, but a better service exists from the more structured response in the checkEntityResults section of a response.
The summary resultState is the first field to check. Although the API documentation gives an accurate description of the various states, there are a large number of subtleties that can creep in given the vast array of potential check results possible. With that in mind, the following is a guide to reading the response.
Check state for an individual data point
UNCHECKED: Check hasn’t yet been performed.NOT_SUPPORTED: The requested check type or industry function isn’t supported by this connector.CHECKING: Checks are underway.UNPROCESSABLE: The data supplied was unprocessable.NO_MATCH: All checks were complete as far as possible, no records were found that matched the details supplied. No AML checks would have been run.CHECKED_PARTIAL_SUCCESS: Indicates that we were able to partially match an entity, but not all checks completed.CHECKED_SUCCESS_WITH_NOTES: All checks are complete, but there are some notes (e.g. PEP or sanctions).CHECKED_SUCCESS_CLEAR: All checks are complete, enough details were verified and cleared to ensure that this person meets your KYC/AML requirements. No additional action is required.CHECKED_FAILED: Some checks were attempted, but there was a hard failure along the way and we’ve had to stop.
You should always look to the `Action.Recommended` KVP flag for a final recommended disposition, especially for **CHECKED_PARTIAL_SUCCESS** and **CHECKED_SUCCESS_WITH_NOTES**, just to be sure.
If you receive an Action.Recommended of FAIL or FAIL_MANUAL, you should look at the following:
- KVP
Fail.Reason.*- that will give a basic indication as to why the entity failed. - KVP
portal.issue.summary- this gives a quick indicator of issues that need attention. - KVP
Info.*MatchCount- that will tell you how many items matched - use this for partial failures. - KVP
Important.HasSantions- the individual is marked as sanctioned - you should use the portal to verify these results and set to false or true positive. - KVP
Important.Duplicate- the individual has been marked as a duplicate. Use the portal tools to confirm or mark as a false positive. - KVP
Important.Blacklist- the individual has been marked as blacklisted. Use the portal tools to confirm or mark as a false positive.
When the Action.Recommended is “REFER”, you should look at:
- KVP `Review.Reason.* and KVP portal.issue.summary - as above, these give a brief description of the issues that need addressing.
- KVP `Risk.Level - the entity might just be too high a risk.
- KVPs
Issue.IsPEP,Issue.OnWatchlist,Issue.HasMedia- indicates that the entity has potential AML issues that need review via the portal.