Using the Screening APIs
The Screening APIs allow the Fenergo UI and API consumers to interact with the screening functionality of the application. The Command and Query APIs are linked opposite and contain the methods to create new screening batches, check the results and then action those results.
| APIs Referenced |
|---|
| Screening Command |
| Screening Query |
Sample Use Case for Screening Entity Data
AS an API consumer:
GIVEN: I need to screen one or more Legal Entities against my configured Screening Provider
WHEN: I have gathered all the legal entity data
THEN: I want to call an API to pass in the data to search for and resolve Screening Matches.
Steps to satisfy the use case
The steps involved to address this use case via the FenX APIs are as follows:
- Create a New Screening Batch against a configured Provider and Pass in Legal Entity Data.
- Get the Batch Provider Status for the Screening Request.
- Get the Matches Results for entity (or all entities)
- Resolve the matches
- Complete and Close the Batch
Create a New Screening Batch Request
This URL endpoint {{baseURL}}/screeningcommand/api/batch creates a screening batch that will trigger an asynchronous request for each screening provider configured for the tenant. A batch can contain one or more legal entities.
{
"data": {
"entities": [
{
"legalEntityId": "string",
"searchCriteria": {
"fullName": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dateOfBirth": "string",
"gender": "string",
"legalEntityName": "string",
"type": "string",
"address": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"postalCode": "string",
"country": "string",
"stateProvince": "string",
"type": "string"
},
"idNumber": "string",
"phoneNumber": "string",
"emailAddress": "string",
"nationality": "string",
"countryOfResidence": "string",
"placeOfBirth": "string",
"citizenship": "string",
"registeredCountry": "string",
"subtype": "string",
"uniqueId": "string"
},
"entityAliases": [
{
"id": "string",
"aliasType": "string",
"fullName": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"legalEntityName": "string"
}
]
}
],
"journeyId": "string",
"processId": "string",
"providers": [
{
"providerId": "string",
"configurationSetId": "string"
}
]
}
}
Note: providers field is not mandatory. If no providers are specified, the batch will be created with all the active providers in the configuration. If the providerId is sent but configurationSetId is not sent, the default configuration set will be used.
Note: entityAliases is not mandatory. If no aliases are specified, the batch will be created with only the PrimaryName of the entity.
Screening Batch Response
{
// A batchId, which uniquely identifies the request, will be sent back in real time.
"data": {
"batchId": "string"
},
"messages": [
{
"message": "string",
"type": "string"
}
]
}
The response contains the "batchId" which is used to identify all the screening activity.
Get all Screening Entities for a Batch
As a Screening Batch can contain requests for multiple entities you can check the all entities that are part of the batch. Sent a HTTP GET to the following URL: {{baseURL}}/screeningquery/api/v3/batch/{batchId}/entity
{
// The data response object contains an array of Entities
"data": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legalEntityId": "string",
"entityName": "string",
"externalIds": [
{
"source": "string",
"entityAliasId": "string",
"name": "string",
"value": "string"
}
],
"searchCriteria": {
"fullName": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dateOfBirth": "string",
"gender": "string",
"legalEntityName": "string",
"type": "string",
"address": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"postalCode": "string",
"country": "string",
"stateProvince": "string"
},
"idNumber": "string",
"phoneNumber": "string",
"emailAddress": "string",
"nationality": "string",
"countryOfResidence": "string",
"placeOfBirth": "string",
"citizenship": "string",
"registeredCountry": "string"
},
"entityAliases": [
{
"id": "string",
"aliasType": "string",
"fullName": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"legalEntityName": "string"
}
]
}
],
"messages": [
{
"message": "string",
"type": "string"
}
]
}
Understanding the Get Screening Matches Response
This response above is a snippet of a full response that you will get from your screening tenant. The data response is an array which contains multiple entities.
"id"is the unique ID of the entity to be screened, and will be the same for a specific LegalEntityId within batches. A batch can contain one or more entities."legalEntityId"is the Legal Entity Id for the entity being screened (this is the id from Entity Data domain)."searchCriteria"is the Search Criteria which is sent to the screening provider for the Legal Entity."entityAliases"are the alias information sent to the screening provider for the Legal Entity."externalIds"are the external ids returned by the screening provider for the Legal Entity. These can be used to correlate the entity in the screening provider system. EntityAliasId will be "PrimaryName" for the main name of the entity and the alias id for the aliases.
Get Screening Matches for a specific Entity
You can specify an Entity Id in this request to retrieve the matches for that Entity. The API Endpoint for this call is GET {{baseURL}}/screeningquery/api/v3/batch/{batchId}/entity/{entityId}/match
{
// The data response object contains an array of Entities
"data": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"entityAliasIds": ["string"],
"status": "string",
"reason": "string",
"comments": "string",
"matchData": {
"providerId": "",
"externalId": "string",
"externalIds": [
{
"entityAliasId": "string",
"value": "string"
}
],
"name": "string",
"aliases": ["string"],
"gender": "string",
"dateOfBirth": "string",
"country": "string",
"entityType": "string",
"matchScore": 0,
"providerSourceName": "string",
"providerSourceUrl": "string",
"addresses": [
{
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"postalCode": "string",
"country": "string",
"stateProvince": "string"
}
],
"citizenship": "string",
"nationality": "string",
"placeOfBirth": "string",
"countryOfResidence": "string",
"additionalInfo": [
{
"name": "string",
"value": "string"
}
],
"categories": ["string"],
"sources": ["string"],
"registeredCountry": "string"
}
}
],
"messages": [
{
"message": "string",
"type": "string"
}
]
}
Each Match has an Id which can be used to resolve.
"entityAliasIds"are the alias ids that returned this match in the provider. This can be "PrimaryName" or the alias id sent in the create batch request."externalId"is the unique id of the match in the screening provider system. This is now deprecated, and you should use the externalIds array instead."externalIds"are the external ids returned by the screening provider for the match (one per entity alias that caused this match). These can be used to correlate the match in the screening provider system. EntityAliasId will be "PrimaryName" for the main name of the entity and the alias id for the aliases.
Resolve the matches for all Entities
A Screening Batch can have matches resolved using the Screening Command API endpoint opposite. This endpoint accepts the BatchId in the URL and allows an API Consumer to update the status, reason and comments of a list of matches. The API Endpoint URL is {{baseURL}}/screeningcommand/api/batch/{batchId}/matches
{
"data": [
{
"entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"matches": [
{
"matchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"reason": "string",
"comments": "string"
}
]
}
]
}
// RESPONSES:
- 202: Success
- 400: Bad request
- 500: Internal server error
Understanding the Resolve Matches Response
When resolving matches for entities - each matchId which is unresolved must be updated.
- the
"data"request is an array with an entry for each entity from the batch. "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"for the Legal Entity against which the match was found."matches"are updates for the Legal Entity. Each Match has an Id, status, reason and comments.
Resolve Matches Error Response
{
// If there is an error in the response information about any errors will be returned.
"data": "string",
"messages": [
{
"message": "string",
"type": "string"
}
]
}
Complete and Close the Batch
Once all matches have been updated, a batch can then be closed. There is no Request Body required in this request. A HTTP PUT can be sent to the following URL: {{baseURL}}/screeningquery/api/batch/{batchId}/complete
Complete Batch Responses
// RESPONSES:
- 202: Success
- 400: Bad request
- 500: Internal server error
{
// If there is an error in the response information about any errors will be returned.
"data": "string",
"messages": [
{
"message": "string",
"type": "string"
}
]
}
Once you get a success response, the batch is not automatically closed. It will send a call to the providers' resolve matches endpoint and it will be closed once it gets a correct response from all the providers of the batch. If one of the providers fails to resolve the matches, the batch will remain open. You can check the status of this by using the query batch endpoint.