Managing Watchlists Via API
Introduction
This document will describe how to create watchlists and manage watchlist members using the TrustX API. For more details on watchlists and how they are managed through the Backoffice, see the Managing Watchlists guide.
API Access and Permissions
Before getting started, access to the TrustX API is required. A token grants access to the caller to invoke API calls on TrustX. Once the token is generated it can be reused, however it must be noted that the token has a 'time to live'. Once the 'time to live' has expired a new token must be generated.
When calling the API to issue a token, you will need to provide an API Key. This API Key is obtained from an API Key's secret. See the API Key Guide for information on how to manage API keys.
When the api/arthr/apiKeys/issue API is invoked, the response to this call provides a bearer token. This bearer token is used to authenticate subsequent calls to TrustX.
A Token is created by invoking the API call below:
POST https://{{tenant}}.{{region}}.trustx.com/api/arthr/apiKeys/issueContent-Type: application/jsonX-API-Key: {{apiKey}}{}The permissions required for the APIs calls within the watchlist guide are as follows (note: replace {tenantid} with literal value):
TNT#{{tenantid}}#WatchlistManager*Creating a Watchlist
A new watchlist can be created using the TrustX API by sending a POST query to the /api/watchlist-manager/facewatchlists endpoint.
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/facewatchlistsContent-Type: application/jsonAuthorization: Bearer {{token}}{ "name":"Example_Watchlist", "description":"This is an example watchlist", "status":"ACTIVE", "type":"FACEV6"}Example Response:
{ "id": "TFPMJFBB2HMY2DTNVCXKO4WC2Y", "tenantId": "{{tenant}}", "name": "Example_Watchlist", "description": "This is an example watchlist", "type": "FACEV6", "status": "ACTIVE", "maxSize": 10000, "numMembers": null, "expireMembersAfter": "21000010000", "createdDtm": "2024-01-26T13:02:09.408Z", "lastUpdatedDtm": "2024-01-26T13:02:09.408Z", "createdBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A", "lastUpdatedBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A"}Adding a Member to a Watchlist
The api/watchlist-manager/facewatchlists/{{watchlistId}}/watchlist-members endpoint is used to add a new watchlist member to an existing watchlist. The face image should be passed as a base64 encoded string.
In the example below the {{watchlistId}} variable is substituted for the value of the 'id' for the watchlist created in the previous example, e.g. TFPMJFBB2HMY2DTNVCXKO4WC2Y.
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/facewatchlists/{{watchlistId}}/watchlist-membersContent-Type: application/jsonAuthorization: Bearer {{token}}{ "firstName": "John", "lastName": "Doe", "email": "john.doe@gmail.com", "phoneNumber": "+1 (415) 273-9164", "faceImage": "{{base64Img}}", "watchlistId": "{{watchlistId}}", "attributes": { "aka":"Jonathan Doe" }, "expireAtDtm": "2024-02-19T11:27:47.152Z"}Example Response:
{ "tenantId": "naps", "watchlistName": "Example_Watchlist", "watchlistId": "TFPMJFBB2HMY2DTNVCXKO4WC2Y", "storeSamples": true, "firstName": "John", "lastName": "Doe", "phoneNumber": "+1 (415) 273-9164", "email": "john.doe@gmail.com", "attributes": { "aka": "Jonathan Doe" }, "expireAtDtm": "2100-01-01T00:00:00.040703999Z", "id": "SRMUUIJSN6VG7UR6TKZAP6HTK4", "createdDtm": "2024-01-26T14:32:47.041Z", "lastUpdatedDtm": "2024-01-26T14:32:47.041Z", "createdBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A", "lastUpdatedBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A"}Adding a Member Using StoreSample
Users can also add a watchlist member where the face image is not stored and will not be visible within the Backoffice application. This can be achieved by setting the storeSamples property to false. By default, this property will be set to true. Below is an example request and response.
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/facewatchlists/{{watchlistId}}/watchlist-membersContent-Type: application/jsonAuthorization: Bearer {{token}}{ "firstName": "John", "lastName": "Doe", "email": "john.doe@gmail.com", "phoneNumber": "+1 (415) 273-9164", "storeSamples": "false" "faceImage": "{{base64Img}}", "watchlistId": "{{watchlistId}}", "attributes": { "aka":"Jonathan Doe" }, "expireAtDtm": "2024-08-19T11:27:47.152Z"}Example Response:
{ "tenantId": "naps", "watchlistName": "Example_Watchlist", "watchlistId": "TFPMJFBB2HMY2DTNVCXKO4WC2Y", "storeSamples": false, "firstName": "John", "lastName": "Doe", "phoneNumber": "+1 (415) 273-9164", "email": "john.doe@gmail.com", "attributes": { "aka": "Jonathan Doe" }, "expireAtDtm": "2100-01-01T00:00:00.040703999Z", "id": "SRMUUIJSN6VG7UR6TKZAP6HTK4", "createdDtm": "2024-01-26T14:32:47.041Z", "lastUpdatedDtm": "2024-01-26T14:32:47.041Z", "createdBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A", "lastUpdatedBy": "acwc@Tenant@AccessToken.I3TJAMOK7AA2OQSIKYFAR4NX7A"}Deleting a Watchlist Member
A watchlist member can be deleted by sending a DELETE query to the /api/watchlist-manager/facewatchlists/{{watchlistId}}/watchlist-members/endpoint.
It can take approximately 20 minutes before a deleted watchlist member is completely removed from the TrustX system.
Example Request:
DELETE https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/facewatchlists/{{watchlistId}}/watchlist-members/{watchlistMemberId}Content-Type: application/jsonAuthorization: Bearer {{token}}{}Perform Watchlist Match
A watchlist match can be performed via the API to determine whether a face image appears as a member of a specified watchlist. This can be achieved by contacting the api/watchlist-manager/facewatchlists/match endpoint.
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/watchlist-manager/facewatchlists/matchContent-Type: application/jsonAuthorization: Bearer {{apiKey}}{ "refFaceImage": "{{base64Img}}", "matchThreshold": 0.205245, "maxCandidates": 10, "watchlistName": "Example_Watchlist"}Example Response:
{ "watchlistId": "6ZOQIV7H2QGZH3TNUSLLBBTIWU", "createdDtm": "2024-01-25T13:05:50.551369739Z", "duration": 1197, "statusCode": 200, "statusMsg": null, "threshold": 0.205245, "maxCandidates": 10, "candidates": [ { "score": 0.0, "memberId": "4TYA2W2FIDL7IRIQ6F5E73ZVVM" } ]}