Watchlist Screening

Retrieve the latest watchlist screening result for a verification entity or a specific stakeholder. Watchlist screening checks individuals and entities against sanctions lists, politically exposed persons (PEP) databases, and criminal records.

Overview

When screening completes, a webhook is sent with the updated idvRisk and a screening summary. Use the endpoints below to retrieve full screening details including matched sources and records.

These read-only endpoints return the most recent screening result, including:

Matches — any hits found, grouped by source list
Sources checked — an audit trail of every source that was checked

Two endpoints are available depending on whether you are retrieving the screening result for the verification entity or for a specific stakeholder:

GET /v5/verifications/:trace/watchlist/latest - Get entity screening result
GET /v5/verifications/:trace/stakeholders/:stakeholderId/watchlist/latest - Get stakeholder screening result

Screening is triggered automatically when a verification reaches verified status. See Test values for controlling screening outcomes in the Preview environment.

GET/v5/verifications/:trace/watchlist/latest

Get entity screening

Retrieve the latest watchlist screening result for the verification entity.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.

Response fields

Field	Type	Description
`screeningId`	string	Unique identifier for the screening run.
`trace`	string	The verification trace.
`totalHits`	number	Total individual record hits returned by the provider.
`hasMatches`	boolean	Whether any matches were found.
`matchedSources`	array	Sources that had hits, each containing matched records. See Matched sources.
`sourcesChecked`	array	Audit trail of every source checked. See Sources checked.
`triggeredByAction`	string	What triggered the screening: `"on-verified"`, `"manual-api"`, `"manual-portal"`, or `"scheduled"`.
`triggeredByUid`	string	UID of the user who triggered the screening (optional, present on manual triggers).
`triggeredByEmail`	string	Email of the user who triggered the screening (optional, present on manual triggers).
`screenedAt`	number	Unix timestamp of when the screening was performed (milliseconds).
`screenedTime`	string	Human-readable screening time.
`createdAt`	number	Unix timestamp of when the record was created (milliseconds).
`createdTime`	string	Human-readable creation time.

Error responses

Status Code	Error Type	Description
404	`not_found`	No watchlist screening exists for this verification.

Request

GET

/v5/verifications/:trace/watchlist/latest

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/watchlist/latest" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-02-28T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/watchlist/latest",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Watchlist screening retrieved successfully.",
  "help": null,
  "status": "success",
  "data": {
    "screeningId": "scr-abc123",
    "trace": "abc123-verification-trace",
    "totalHits": 0,
    "hasMatches": false,
    "matchedSources": [],
    "sourcesChecked": [
      {
        "sourceId": "au-dfat-sanctions",
        "sourceName": "DFAT Consolidated List",
        "sourceCountry": "AUS",
        "sourceType": "SANCTION",
        "matched": false
      }
    ],
    "triggeredByAction": "on-verified",
    "screenedAt": 1740715200000,
    "screenedTime": "28/02/2026 04:00:00",
    "createdAt": 1740715200000,
    "createdTime": "28/02/2026 04:00:00"
  },
  "error": null
}

Error response (404)

{
  "timestamp": "2026-02-28T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/watchlist/latest",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 404,
  "message": "Not found",
  "help": null,
  "status": "error",
  "data": null,
  "error": {
    "type": "not_found",
    "details": [
      {
        "message": "Watchlist screening not found",
        "code": "not_found",
        "path": ["screening"]
      }
    ]
  }
}

GET/v5/verifications/:trace/stakeholders/:stakeholderId/watchlist/latest

Get stakeholder screening

Retrieve the latest watchlist screening result for a specific stakeholder within a verification.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
stakeholderId
Type
string
Description
The unique identifier for the stakeholder.

Response fields

The response fields are identical to the entity screening response, with the addition of:

Field	Type	Description
`stakeholderId`	string	The stakeholder that was screened.

Error responses

Status Code	Error Type	Description
404	`not_found`	No watchlist screening exists for this stakeholder.
422	`validation_error`	Invalid stakeholder ID (e.g. empty or whitespace).

Request

GET

/v5/verifications/:trace/stakeholders/:stakeholderId/watchlist/latest

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/stakeholders/{stakeholderId}/watchlist/latest" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-02-28T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/stakeholders/:stakeholderId/watchlist/latest",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "stakeholderId": "sth-director-001"
  },
  "statusCode": 200,
  "message": "Watchlist screening retrieved successfully.",
  "help": null,
  "status": "success",
  "data": {
    "screeningId": "scr-def456",
    "trace": "abc123-verification-trace",
    "stakeholderId": "sth-director-001",
    "totalHits": 1,
    "hasMatches": true,
    "matchedSources": [
      {
        "sourceId": "nz-pep-list",
        "sourceName": "New Zealand PEP List",
        "sourceDescription": "Politically exposed persons in New Zealand",
        "sourceLink": "https://example.com/nz-pep",
        "sourceCountry": "NZL",
        "sourceType": "PEP",
        "records": [
          {
            "name": "Jane Smith",
            "entityType": "individual",
            "sourceType": "PEP",
            "pepType": "national",
            "pepLevel": 2,
            "positions": ["Member of Parliament"],
            "politicalParties": ["Example Party"]
          }
        ]
      }
    ],
    "sourcesChecked": [
      {
        "sourceId": "nz-pep-list",
        "sourceName": "New Zealand PEP List",
        "sourceCountry": "NZL",
        "sourceType": "PEP",
        "matched": true
      }
    ],
    "triggeredByAction": "on-verified",
    "screenedAt": 1740715200000,
    "screenedTime": "28/02/2026 04:00:00",
    "createdAt": 1740715200000,
    "createdTime": "28/02/2026 04:00:00"
  },
  "error": null
}

Matched sources

Each entry in matchedSources represents a source list that returned one or more hits. Records are grouped by source.

Field	Type	Description
`sourceId`	string	Unique identifier for the source list.
`sourceName`	string	Human-readable name of the source list.
`sourceDescription`	string	Description of the source list.
`sourceLink`	string	URL to the source list.
`sourceCountry`	string	Country the source list belongs to (ISO 3166-1 alpha-3, e.g. `"AUS"`, `"USA"`).
`sourceType`	string	`"SANCTION"`, `"PEP"`, `"CRIMINAL"`, or `"OTHER"`.
`records`	array	Individual match records from this source. See Match records.

Match records

Each record in records represents a single matched individual or entity from a source list.

Field	Type	Description
`name`	string	Name of the matched person or entity.
`entityType`	string	`"individual"` or `"entity"`.
`sourceType`	string	`"SANCTION"`, `"PEP"`, `"CRIMINAL"`, or `"OTHER"`.
`aliasNames`	string[]	Known aliases (optional).
`dateOfBirth`	string[]	Known dates of birth (optional).
`citizenship`	string[]	Known citizenships (optional).
`address`	string[]	Known addresses (optional).
`pepType`	string	Type of PEP classification (optional, PEP records only).
`pepLevel`	number	PEP level (optional, PEP records only).
`positions`	string[]	Known positions held (optional, PEP records only).
`politicalParties`	string[]	Known party affiliations (optional, PEP records only).
`sanctionDetails`	string[]	Details of the sanction (optional, sanction records only).
`links`	string[]	Reference URLs (optional).

Sources checked

Each entry in sourcesChecked is an audit record of a source list that was checked, regardless of whether it produced any matches.

Field	Type	Description
`sourceId`	string	Unique identifier for the source list.
`sourceName`	string	Human-readable name of the source list.
`sourceCountry`	string	Country the source list belongs to (ISO 3166-1 alpha-3, e.g. `"AUS"`, `"USA"`).
`sourceType`	string	`"SANCTION"`, `"PEP"`, `"CRIMINAL"`, or `"OTHER"`.
`lastChecked`	string	When the source was last checked (optional).
`matched`	boolean	Whether this source returned any hits.