Identity 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/CreateEnrollmentWithIndividual

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:

An endpoint for token generation. The token endpoint must have the request body grant_type= client_credentials.
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/CreateEnrollmentWithIndividual

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

# Request Body
{
  "CallbackUrl": "callbackUrl",
  "Frequency": "Monthly",
  "IndividualToMonitor": {
    "FirstName": "FirstName",
    "LastName": "LastName",
    "DateOfBirth":"YYYY-MM-DD"
  },
  "SkipInitialCallback": false,
  "CustomerReferenceId": "123456",
  "ServiceName": "Watchlist"
}

Enrollment API Call

FieldName	Required	Description
CallbackUrl	True	Callback URL/Webhook for customer endpoint on which to return individual information
Frequency	True	Frequency of re-querying by Ongoing Monitoring, possible values include: Weekly Monthly Quarterly Yearly
FirstName	False	First name of Individual
LastName	True	Last name of Individual
DateOfBirth	False	Date of Birth of Individual
SkipInitialCallback	False	The 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.
CustomerReferenceId	False	Optional ID to cross-reference with the customer's database
ServiceName	True	The service name is Watchlist

Sample API Response

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

Sample Callback Response (WatchlistState = 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,
            "num_PEP_hits": 1
        },
        "WatchlistFullName": "Tom Marvolo Riddle",
        "WatchlistHitDetails": {
            "WL_results": [
                {
                    "score": 1,
                    "individualName": "Tom Marvolo Riddle",
                    "aliasList": "Lord Voldemort; You-Know-Who; He-Who-Must-Not-Be-Named; The Dark Lord",
                    "identifier": "Unique ID: HW32189 | Azkaban ID: 14196",
                    "subjectMatched": "Tom Marvolo Riddle",
                    "dateOfBirth": "31/12/1926",
                    "nationality": "British",
                    "sourceListType": "Ministry of Magic Sanctions List",
                    "sourceRegion": "Europe",
                    "remarks": "Date Designated: 06/07/1945 | Last Updated: 18/12/1995 | Positions: Chief Death Eater",
                    "caution": "Sanctions Imposed: Asset freeze, Travel Ban, No Broom List",
                    "URL": "https://www.wizardingworld.com/"
                },
                {
                    "score": 0.95,
                    "individualName": "Tom Riddle",
                    "aliasList": "Lord Voldemort; The Dark Lord",
                    "identifier": null,
                    "subjectMatched": "Tom Riddle",
                    "dateOfBirth": "31/12/1926",
                    "nationality": "British",
                    "sourceListType": "The Magical Congress of the United States of America Sanctions List",
                    "sourceRegion": "North America",
                    "remarks": "Date Designated: 06/07/2020 | Last Updated: 18/12/2021 | Positions: Head of the Investigative Committee of Russia",
                    "caution": "Sanctions Imposed: Asset freeze, Travel Ban",
                    "URL": "https://www.wizardingworld.com/"
                }
            ],
            "AM_results": [
                {
                    "score": 0.95,
                    "subjectMatched": "Tom Riddle",
                    "text": "Hogwarts increases security against former student Tom Riddle",
                    "URL": "https://thedailyprophet.net/"
                },
                {
                    "score": 0.9,
                    "subjectMatched": "Voldemort",
                    "text": "Death Eater Terror Continues as Voldemort returns",
                    "URL": "https://thedailyprophet.net/"
                }
            ],
            "PEP_results": [
                {
                    "score": 1,
                    "name": "Tom Marvolo Riddle",
                    "dateOfBirth": "31/12/1926",
                    "country": "United Kingdom",
                    "professionalHistory": [
                        "Lord Voldemort",
                        "You-Know-Who",
                        "He-Who-Must-Not-Be-Named",
                        "The Dark Lord"
                    ]
                }
            ]
        }
    }
}

Sample Callback Response (WatchlistState = No Hit)

{
  "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 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/ENROLLMENTID

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

Sample Unenrollment Response

Enrollment deleted

Sample Update Frequency Request

PUT /Enrollment/ENROLLMENTID/frequency?frequencyName=NEWFREQUENCYINTERVAL

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

Frequency intervals can be found here

After the frequency update, the next scan will occur at "Date Frequency Changed + Frequency Interval." For example, if the frequency for an enrollment was updated from Monthly to Weekly on January 1st the next scan will be January 8th.

Sample Update Frequency Response

{
    "StatusCode": 200,
    "Message": "PUT Request successful.",
    "Result": "successfully updated enrollment frequency to weekly by id d1102918-b1c9-4866-b533-1d4dbf657519"
}

Sample Get Enrollment History Request

This endpoint takes in EnrollmentID and returns all watchlist hits for the entity.

GET /Enrollment/History/ENROLLMENTID

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

Sample Get Enrollment History Response

{
  "StatusCode": 200,
  "Message": "GET Request successful.",
  "Result": [
    {
      "VerificationDoneOnDate": "2023-04-27T17:02:56.080978",
      "EnrollmentId": "91f4baa7-c3a0-42f9-826b-f95051c378dc",
      "MonitoringResult": {
        "WatchlistState": "Potential Hit",
        "WatchlistData": {
          "num_WL_hits": 1,
          "num_AM_hits": 0,
          "num_PEP_hits": 0
        },
        "WatchlistFullName": "Tom Marvolo Riddle",
        "WatchlistHitDetails": {
          "WL_results": [
            {
              "score": 1,
              "individualName": "Tom Marvolo Riddle",
              "aliasList": "Lord Voldemort; You-Know-Who; He-Who-Must-Not-Be-Named; The Dark Lord",
              "identifier": "Unique ID: HW32189 | Azkaban ID: 14196",
              "subjectMatched": "Tom Marvolo Riddle",
              "dateOfBirth": "31/12/1926",
              "nationality": "British",
              "sourceListType": "Ministry of Magic Sanctions List",
              "sourceRegion": "Europe",
              "remarks": "Date Designated: 06/07/1945 | Last Updated: 18/12/1995 | Positions: Chief Death Eater",
              "caution": "Sanctions Imposed: Asset freeze, Travel Ban, No Broom List",
              "URL": "https://www.wizardingworld.com/"
            }
          ],
          "AM_results": [],
          "PEP_results": []
        }
      }
    }
  ]
}

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"
}