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

Three endpoints are available — two for retrieving the latest screening result, and one for triggering a new screening run on demand:

GET /v5/verifications/:trace/watchlist/latest - Get entity screening result
GET /v5/verifications/:trace/stakeholders/:stakeholderId/watchlist/latest - Get stakeholder screening result
POST /v5/verifications/:trace/watchlist - Trigger a new screening run

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.

POST/v5/verifications/:trace/watchlist

Trigger a rescreen

Dispatches a watchlist rescreen for an existing verification. This is an asynchronous operation — the endpoint returns a jobId immediately, and the full screening cascade (stakeholders → stakeholder risk → entity → entity risk) runs in the background.

Poll GET /v5/verifications/:trace/jobs/watchlist/:jobId to check lifecycle status. See the Jobs reference for the full status machine and the in-flight debounce behavior.

Gated against concurrent runs. If a rescreen is already in flight, the endpoint returns 429 with the jobId of the in-flight dispatch so you can poll that instead of starting a new one.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification to rescreen. Must refer to a v5 verification.

Request body

No fields. Send an empty JSON object ({}).

Response fields

Field	Type	Description
`triggered`	boolean	Always `true` on a 200 response.
`jobId`	string	The dispatched job's ID. Use it to poll status via the jobs endpoint.

Error responses

Status Code	Error Type	Description
404	`not_found`	No v5 verification exists for the given trace.
429	`too_many_requests`	A rescreen is already in flight for this verification. Response message includes the conflicting job's `jobId`; poll it instead of retrying immediately.

Request

POST

/v5/verifications/:trace/watchlist

curl -X POST "https://api.bronid.com/v5/verifications/{trace}/watchlist" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "timestamp": "2026-02-28T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/watchlist",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Watchlist rescreen dispatched.",
  "help": null,
  "status": "success",
  "data": {
    "triggered": true,
    "jobId": "V1StGXR8_Z5jdHi6B-myT"
  },
  "error": null
}

Error response (429 – already in flight)

{
  "timestamp": "2026-02-28T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/watchlist",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 429,
  "message": "Watchlist rescreen already in progress (jobId: V1StGXR8_Z5jdHi6B-myT). Poll its job doc for status.",
  "help": null,
  "status": "error",
  "data": null,
  "error": {
    "type": "too_many_requests",
    "details": [
      {
        "message": "Conflicting in-flight job: V1StGXR8_Z5jdHi6B-myT",
        "code": "too_many_requests",
        "path": ["trace"]
      }
    ]
  }
}