TrustX Watchlists enables the recording and storing of a visitor ID (device/browser fingerprint) to a watchlist for device-based fraud detection. This functionality provides the following security benefits:
- Blocking devices used in fraud attacks
- Flagging devices with suspicious behavior
- Multi-accounting detection
- Account takeover prevention
- Bot detection
Creating a Visitor ID Watchlist
A visitor ID Watchlist stores a list of Persons of Interest by the visitor ID. To create a visitor ID Watchlist, follow the steps below.
- Log in to the Backoffice application and select Watchlists from the left-side vertical menu.
- From the Watchlists landing page, ensure that 'New Management' is selected and click the 'New Watchlist' button.
- Set the name of the Watchlist and set the Type to 'Visitor ID'.
- Click the 'Save' button to save the new Watchlist.
Add Watchlist Entry
A visitor ID Watchlist entry can be added in various methods. This section will cover each potential method.
Add Watchlist Entry via Backoffice
- Navigate to the Watchlists page in the Backoffice application.
- Find the name of the visitor ID Watchlist that will be updated.
- Click the 'Manage Entries' button to open a list of entries currently within the Watchlist.
- Click the 'Add New Entry' button. A pop-up modal will appear where details about the new Watchlist entry can be defined.
- Each new entry can contain the following information:
| Field Name | Type | Description |
|---|---|---|
| Visitor ID | String | Unique device/browser fingerprint (max 100 chars) |
| Note | String | Optional additional information regarding the entry. |
| Expiry Date | Date-Time | ISO 8601 duration after which the entry will be automatically deleted (e.g., PT1H, P1D). Converted to UTC timestamp by the activity. |
- Once all fields are finalized, click the 'Create Entry' button to save the new Watchlist member.
Add Watchlist Entry via Process Definition
A Watchlist member can also be added from a Process Definition using the 'Add Visitor ID Watchlist Entry v1'.
Step 1 - Create a Process Definition
- Create a new Process Definition by navigating to Process Definitions > New Process Definition in the Backoffice application.
- Add a 'Create Start Event' to the Process Designer.
- Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
- Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.
- Click the 'End' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
Step 2 - Add a Visitor ID to a Watchlist
- From the Process Designer, add an 'Add Visitor ID Watchlist Entry v1' activity. Connect the activity to the 'Start' event.
- This activity includes the following input parameters:
| Parameter | Description | Type | Default |
|---|---|---|---|
| Expire After | ISO 8601 duration after which the entry will be automatically deleted (e.g., PT1H, P1D). Converted to UTC timestamp by the activity. | Date-Time | |
| Visitor ID | Unique device/browser fingerprint (max 100 chars) | String | |
| Watchlist Name | The name of the Watchlist to be added. | String |
- Update the 'Visitor ID' input parameter to include the ID that will be added to the Watchlist.
- The activity includes one error boundary event, "Duplicate Watchlist Entry", which is triggered when the Visitor ID added to the Watchlist is a duplicate of an existing Visitor ID currently in the Watchlist.
- Once the Process Definition has been finalized, click the 'Save & Deploy' button to complete the creation process.
Step 4 - Test the Process Definition
This section will describe how to test the Process Definition created above by generating a Process Token. After completing the flow, results of the Process Instance can be viewed from the Process Instances page.
- To test the Process Definition, create a new Process Token by navigating to the Process Definitions > Process Tokens page.
- Click the 'New Process Token' button found on the top-right of the page to start creating a new token. A popup modal will appear where details of the token can be entered.
- Once the token is created, scan the QR code or follow the link to begin the flow. The specified Visitor ID will be added to the Watchlist.
- Watchlist entries can be viewed by navigating to the Watchlists > Watchlist > Manage Entries page in the Backoffice.
Add a Watchlist Entry via TrustX API
To add a Watchlist entry via the TrustX API, the following tenant permissions are required:
Permissions:
The following query adds a new entry to the watchlist. The entry type must match the Watchlist type.
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/watchlists/{watchlistId}/entriesContent-Type: application/jsonAuthorization: Bearer {{token}}{ "type": "visitorID", "value": "abc123def456ghi789", "expireAtDtm": "2025-11-17T10:30:00Z"}##
Searching a Visitor ID Watchlist
Multiple methods can be used to search for a Watchlist match against a Visitor ID such as the TrustX API, Backoffice application, or via a Process Definition. This section will describe how to perform a Watchlist search using each of the listed methods and how to react to search results.
Searching via Backoffice
It is possible to search for a Watchlist match using the Backoffice 'Test Watchlist' functionality. As the name suggests, this method is primarily intended for testing purposes.
- Navigate to the Watchlists page in the Backoffice.
- Find the Watchlist to be tested using the search functionality provided.
- Under the 'Actions' column. select the 'Test' icon.
- The test page provides a text field where a list of comma-delimited Visitor IDs can be entered as search parameters.
- If a match is found, the results will be displayed in the table below with the result "Match (Detected)".
It is not possible to action on search results returned. This functionality is intended for testing purposes only.
Searching via Process Definition
The 'Search Visitor ID Watchlist v1' activity can be used to search for a Visitor ID match during a Process Instance. This section will describe how to configure a Process Definition that perform a search against a Watchlist using a defined Visitor ID.
Step 1 - Configure the Process Definition
Step 2 - Perform Search Against Watchlist
- Add a 'Search Visitor ID Watchlist v1' activity to the Process Designer and connect it to the 'Start' event using the 'Global connect tool'.
- The 'Search Visitor ID Watchlist v1' activity includes the following input parameters:
| Parameter | Description | Type | Default |
|---|---|---|---|
| Max Match Results | Maximum number of matches to return (1-100) | Integer | ${10} |
| Search Behavior | Determines how match results are interpreted: BLOCK (match=FAIL, no match=PASS), ALLOW (match=PASS, no match=FAIL), BLOCK_REVIEW (match=REVIEW, no match=PASS), ALLOW_REVIEW (match=REVIEW, no match=FAIL) | String | BLOCK |
| Search Key | The key under which the check result will be stored in the checks object | String | watchlistSearch1 |
| Visitor ID | Unique device/browser fingerprint identifier (max 100 chars) | String | |
| Watchlist Name | Name of the visitor ID watchlist (max 250 chars) | String |
- The 'Search Behavior' property controls how the activity will response to matches.
| Value | Match Found | No Match | Use Case |
|---|---|---|---|
BLOCK | outcome = FAIL | outcome = PASS | Blocklist: Fail the check if the visitor ID is found on the watchlist |
ALLOW | outcome = PASS | outcome = FAIL | Allowlist: Pass only if the visitor ID is found on the watchlist |
BLOCK_REVIEW | outcome = REVIEW | outcome = PASS | Blocklist with Review: Send to review if found, otherwise pass |
ALLOW_REVIEW | outcome = REVIEW | outcome = FAIL | Allowlist with Review: Send to review if found (match needs human verification), otherwise deny (not on allowlist) |
- Results of the search will be stored in the _checks table and can be viewed from the Backoffice application or retrieved using the TrustX API.
Searching via API
The following query searches a watchlist for matches against the provided query. The query type must match the watchlist type. Returns matching entries with scores and metadata.
To search a Watchlist entry via the TrustX API, the following tenant permissions are required.
Permissions:
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/watchlists/{watchlistId}/queriesContent-Type: application/jsonAuthorization: Bearer {{token}}{ "type": "visitorID", "value": "abc123def456ghi789", "maxMatchResults": 10}Example Response:
{ "type": "visitorID", "value": "abc123def456ghi789", "queries": [ { "query": "abc123def456ghi789", "matches": [] } ]}Viewing Results
The results of a Watchlist search attempt can be found in the Backoffice application or retrieved using the TrustX API. This section will describe how to retrieve the results of a search in both cases.
Viewing Results in the Backoffice
To find the results of the Watchlist search in the Backoffice application, follow the steps outlined:
- Log in to the Backoffice and navigate to the Process Instances page.
- Using the search filters provided, find the Process Instance where Watchlist searching was performed.
- Watchlist search results can be found in the
_checkstable, displayed in the Backoffice under the Checks section. This will include the Vistor ID that was tested and the result of the search.
- A list of Watchlist search results can be found in the Watchlist Search Results section.
Example No Match Detected:
Example Match Detected:
The table of results include the following information:
- Query Item - Displays the Visitor ID used to perform the search query.
- Match - The Visitor ID matched against within the Watchlist.
- Result - The result of the Watchlist search.
- Actions - In the event of a match, enables users to see additional details about the Watchlist entry that the Visitor ID was matched against.
Using the blue 'tracking' button under the 'Query Item' column, it is possible to add the Visitor ID directly to a Watchlist. Selecting this button will open a popup modal where the Visitor ID can be added.
