HomeDocumentationSupportRelease NotesSearch Box
Documentation

Business Ongoing Screening

Trulioo Platform Ongoing Monitoring Request

Trulioo Platform Ongoing Monitoring service taps into the Trulioo Watchlist service to perform government sanctions and Adverse Media checks for businesses on a regular basis. The Ongoing Monitoring service contains the same response structure as the Onboarding service, but automatically re-queries the Watchlist database at a set frequency. Entities are enrolled in the Watchlist service to have access to this service.

How Trulioo Platform's Ongoing Monitoring Works

  1. Customers enroll Entities into the Ongoing Monitoring service once the user is onboarded
  2. This information is stored in Trulioo's Identity Enrollment Service including PII and frequency
  3. The Trulioo Platform checks the PII information against a multitude of global watchlist and adverse media sources worldwide
  4. If there is a potential match or a “hit” on the watchlist, further detail is shown in the appended fields
  5. The detailed information provided lets clients determine the applicability of the watchlist hit and determine their next steps
  6. After the time period selected, the Trulioo Platform checks the PII information against the same global watchlist and adverse media sources
  7. If there is a difference in the search outcome, such as the enrolled subject is added to a new watchlist, customers are alerted to the difference (Deltas). The new watchlist hit details are sent to the webhook with the status "hit"
  8. If the outcome is identical to the previous search, customers will receive a "no hit" response to their webhook. Alternatively, customers can configure their account to not receive alerts if the outcome is the same as the previous search. This feature helps reduce notifications and the webhook is only pinged if the watchlist status is "hit"

📘

Our customers can unenroll businesses from the Ongoing Monitoring service at any time

Ongoing Monitoring Input Parameters

Token API Call

Input ParameterDescriptionRequired
ClientIdClientId for Ongoing Monitoring AccountTRUE
ClientSecretClientSecret for Ongoing Monitoring AccountTRUE

Enrollment API Call

Input ParameterDescriptionRequired
Bearer TokenTokenTRUE
PackageIdPackage ID for Ongoing Monitoring Account.TRUE
callbackURLCallback URL/Webhook for customer endpoint on which to return individual informationTRUE
frequencyFrequency of re-querying by Ongoing Monitoring, possible values include:

Weekly
Monthly
Quarterly
Yearly		TRUE
SubjectSubject name of Business or EntityTRUE
SkipInitialCallbackThe default value is false (it does not need to be included in the API request). If set to true, the initial watchlist check will be deferred until the first scheduled check based on frequency.FALSE
CustomerReferenceIdOptional ID to cross-reference with the customer's databaseFALSE
serviceNameThe service name is WatchlistTRUE

📘

Ongoing Monitoring Output Parameters:

The Output Parameters for Trulioo Watchlist's response are the same as the parameters for Onboarding Watchlist.

The Trulioo Platform's Ongoing Monitoring service uses Token Authentication as opposed to Basic Authentication used by the rest of Trulioo's services. We have listed the Token endpoint and a sample API call below for clarity.

Prerequisites

  • Before you get started, make sure you have either a GAPI user account with access to the Identity Enrollment Service
  • You have tested your credentials using the Test Authentication call.

Enrollment API Endpoint

The Enrollment API Endpoint is different from the standard Trulioo endpoint and should only be used to enroll an entity into our Identity Enrolment Service for Ongoing Monitoring.

https://identity-enrollment.trulioo.com

Token Authentication Request

To get the bearer token for authentication, submit a POST call to the endpoint below with the Trulioo client id and client secret given to you by the implementation team.

The bearer token returned then needs to be provided in the header for all subsequent enrollment calls shown under Entity Enrollment

https://identity-enrollment.trulioo.com/Token/ClientCredentials

Sample Token Request

POST /Token/ClientCredentials HTTP/1.1

# Request Header
Content-Type: application/json


# Request Body
{
 "ClientID": "TRULIOO_CLIENTID",
 "ClientSecret": "TRULIOO_CLIENTSECRET"
}

Sample Token Response

{
    "Version": "1.0.0",
    "StatusCode": 200,
    "Message": "POST Request successful.",
    "Result": {
        "Token": TOKEN, 
        "TokenType": "bearer",
        "RefreshToken": REFRESH_TOKEN,
        "ExpiresIn": 3598
    }
}

Entity Enrollment

Prerequisites

  • Before you get started, make sure you have either a GAPI user account with access to the Identity Enrollment Service
  • You have existing knowledge of the Trulioo Platform API.
  • You have generated a Token using the Token Request API Endpoint

API Endpoint

The Enrollment API Endpoint is different from the standard Trulioo endpoint and should only be used to enroll an Entity into our Identity Enrolment Service for Ongoing Monitoring.

https://identity-enrollment.trulioo.com/Enrollment/CreateEnrollmentWithSubject

Webhook Authentication

Webhook authentication is recommended to ensure the security and integrity of the webhook from Trulioo. Authentication allows customers to verify that the webhook request is coming from Trulioo and has not been tampered with during transmission. Trulioo supports “No Webhook authentication”, “Basic Authentication”, or “OAuth Authentication” on the webhook URL.

For Ongoing Screening, a customer's webhook is pinged whenever an entity is rescanned against watchlists, adverse media, or PEPs.

Basic Authentication

Customers requiring Basic Authentication on their webhook will need to provide Trulioo with a username and password. The credentials will be base64 encoded and sent in the request header for each webhook.

Please reach out to Trulioo Support to enable this functionality.

Example webhook request from Trulioo to customer with basic authentication

POST {YOUR_WEBHOOK_URL} HTTP/1.1
Authorization: Basic <base64Encoded USERNAME_FOR_TRULIOO:PASSWORD_FOR_TRULIOO>

{
  "VerificationDoneOnDate": "2023-12-28T22:19:26.8062956Z",
  "EnrollmentId": "43fb1649-ed2b-42a6-9c58-21287cced4a7",
  "MonitoringResult": {
    "WatchlistState": "No Hit",
    "WatchlistData": null,
    "WatchlistFullName": "John Doe",
    "WatchlistHitDetails": null
  }
}

OAuth

To enable OAuth webhook authentication, customers will be required to provide Trulioo with the following:

  1. An endpoint for token generation. The token endpoint must have the request body grant_type=client_credentials.
  2. Client ID and Client Secret for Trulioo’s access to your callback URL.

The bearer token generated will be sent in the request header for each webhook.

Please reach out to Trulioo Support to enable this functionality.

Example Authorization Request from Trulioo to Customer Webhook token endpoint

POST {YOUR_WEBHOOK_URL}/token HTTP/1.1
Authorization: Basic <base64Encoded CLIENTID_FOR_TRULIOO:CLIENTSECRET_FOR_TRULIOO>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example webhook request from Trulioo to customer with bearer token authentication

POST {YOUR_WEBHOOK_URL} HTTP/1.1
Authorization: Bearer <BEARER TOKEN FROM AUTHORIZATION REQUEST>

{
  "VerificationDoneOnDate": "2023-12-28T22:19:26.8062956Z",
  "EnrollmentId": "43fb1649-ed2b-42a6-9c58-21287cced4a7",
  "MonitoringResult": {
    "WatchlistState": "No Hit",
    "WatchlistData": null,
    "WatchlistFullName": "John Doe",
    "WatchlistHitDetails": null
  }
}

Sample Enrollment Request

POST /Enrollment/CreateEnrollmentWithSubject

# Request Header
Content-Type: application/json
PackageId: PACKAGE_ID
Authorization: Bearer BEARER_TOKEN

# Request Body
{
  "CallbackUrl": "callbackUrl.com",
  "Frequency": "Monthly",
  "BusinessEntityToMonitor": {
    "Subject": "Gringotts Wizarding Bank"
  },
  "SkipInitialCallback": false,
  "CustomerReferenceId": "123456",
  "ServiceName": "Watchlist"
}

Enrollment API Call

FieldNameRequiredDescription
CallbackUrlTrueCallback URL/Webhook for customer endpoint on which to return individual information
FrequencyTrueFrequency of re-querying by Ongoing Monitoring, possible values include:

Daily
Weekly
Monthly
Quarterly
Yearly
SubjectTrueName of Business or Entity
SkipInitialCallbackFalseThe default value is false (it does not need to be included in the API request). If set to true, the initial watchlist check will be deferred until the first scheduled check based on frequency.
CustomerReferenceIdFalseOptional ID to cross-reference with the customer's database
ServiceNameTrueThe service name is Watchlist

Sample API Response

{
    "Version": "1.0.0",
    "StatusCode": 200,
    "Message": "POST Request successful.",
    "Result": "EnrollmentID"
}

Sample Callback Response (Watchlist State = Hit)

{
	"VerificationDoneOnDate": "2022-11-15T21:47:11.849303",
	"EnrollmentId": "cf9ddaf7-9ed6-442c-8f8c-8c99455e9ab2",
	"MonitoringResult": {
		"WatchlistState": "Potential Hit",
		"WatchlistData": {
			"num_WL_hits": 2,
			"num_AM_hits": 2
		},
		"WatchlistFullName": "Gringotts Wizarding Bank",
		"WatchlistHitDetails": {
			"WL_results": [{
					"score": 1.0,
					"subjectMatched": "Gringotts Wizarding Bank",
					"entityName": "Gringotts Wizarding Bank",
					"sourceListType": "FEDERAL - Fine - Breached Sanctions",
					"sourceRegion": "United Kingdom",
					"remarks": "Posted Date: 12/19/1973 | Letter Issue Date: 07/26/1973 | Subject: Breached Sanction Violation",
					"caution": "The Gringotts Bank violated the Ministry of Magic sanctions and lent out a sum of 10,000 galleons to the Death Eaters for their marketing initiative",
					"URL": "https://harrypotter.fandom.com/wiki/Gringotts_Wizarding_Bank"
				},
				{
					"score": 0.95,
					"subjectMatched": "Gringotts Bank",
					"entityName": "Gringotts Banks",
					"sourceListType": "MOM - Enforcement - Insufficient Security",
					"sourceRegion": "United Kingdom",
					"remarks": "Issuance Date: 1991-07-31",
					"caution": "The Gringotts Bank has been fined 1,000 galleons by the Ministry of Magic for poor compliance and security and allowing the theft of an object of national importance",
					"URL": "https://harrypotter.fandom.com/wiki/Break-in_of_Gringotts_Wizarding_Bank_(1991)"
				}
			],
			"AM_results": [{
					"score": 0.95,
					"subjectMatched": "Gringotts Bank",
					"text": "Investigations continue into the break-in at Gringotts on 31 July, widely believed to be the work of Dark wizards or witches unknown. Gringotts goblins today insisted that nothing had been taken. The vault that was searched had in fact been emptied the same day. But we're not telling you what was in there, so keep your noses out if you know what's good for you, said a Gringotts spokesgoblin this afternoon",
					"URL": "https://harrypotter.fandom.com/wiki/Break-in_of_Gringotts_Wizarding_Bank_(1991)"
				},
				{
					"score": 0.90,
					"subjectMatched": "Gringotts",
					"text": "Gringotts has recently won 2 new awards for compliance and security as the safety place to store objects except for Hogwarts",
					"URL": "https://thedailyprophet.net/"
				}
			]
		}
	}
}

Sample Callback Response (Watchlist State = No Hit)

{
  "VerificationDoneOnDate": "2023-12-28T22:19:26.8062956Z",
  "EnrollmentId": "43fb1649-ed2b-42a6-9c58-21287cced4a7",
  "MonitoringResult": {
    "WatchlistState": "No Hit",
    "WatchlistData": null,
    "WatchlistFullName": "Business Ltd.",
    "WatchlistHitDetails": null
  }
}

Sample Callback Response (WatchlistState = Error)

An error state will occur if issues arise during enrollment scanning. The callback will receive a response with the monitoring result set to null along with an error message. Trulioo has a retry mechanism in place to guarantee scanning of the enrollment within the specified frequency.

{
  "VerificationDoneOnDate": "2023-12-28T22:19:26.8062956Z",
  "EnrollmentId": "43fb1649-ed2b-42a6-9c58-21287cced4a7",
  "MonitoringResult": null,
  "ErrorMessage": "Failed to retrieve watchlist data"
}

Sample Unenrollment Request

DELETE /Enrollment/ENROLLEMENTID

# Request Header
Content-Type: application/json
PackageId: PACKAGE_ID
Authorization: Bearer BEARER_TOKEN

Sample Unenrollment Response

Enrollment deleted

Sample Resend Callback Request

The endpoint will resend the most recent response to the callback associated with the EnrollmentId

Note: Only the enrollment owner (the user who created the enrollment) can trigger this functionality. 

POST /Enrollment/ENROLLMENTID/ResendCallback 

# Request Header
Content-Type: application/json
PackageId: PACKAGE_ID
Authorization: Bearer BEARER_TOKEN

Sample Resend Callback Response

{
    "StatusCode": 200,
    "Message": "POST Request successful.",
    "Result": "successfully sent callback message"
}