Screening API

The Screening API lets developer accounts check a person or organisation against published sanctions lists, politically exposed persons (PEP), and optional adverse media. Results include scored matches, source attribution, and RCA (relative/close associate) paths where configured.

Credits

Screening uses the same prepaid credit wallet as DVS. Each live screening check consumes 0.5 credits; sandbox screening is free. Purchase credits from Dashboard > Billing.

• Test-environment screening is free and uses predefined test names only. Arbitrary names are blocked
• Each live check deducts 0.5 credits regardless of match outcome
• DVS identity verification deducts 1 credit per live result (Y, N, or D)

Test-environment screening

On the test API, screening does not query the live matching index. On POST /v1/screening with a sk_test_* key, only the accepted test names below are valid - any other name returns 422 with code SANDBOX_SCREENING_NAME_REQUIRED and the full list in testNames.

Accepted test names: screenclear, screensanction, screenpep, screenpossible, screenmultiple, screenmedia, screenrca

Use these to verify your integration handles cleared subjects, strong matches, possible matches, and optional adverse media / RCA paths.

See also the Test Environment page for DVS test records and the MCP server get_sandbox_triggers tool for ready-to-send payloads.

Base URLs

All requests require the X-API-Key header.

Run a screening check

POST /v1/screening

Request body

listFilter options

• topics - e.g. ["sanction", "pep"]
• categories - sanction, pep, adverse_media, other
• includeAdverseMedia - search media mentions (default false)
• includeRcas - include relative/close associates of matched entities (default false)

Example request

curl -X POST https://test-api.veroid.com.au/v1/screening \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_your_key" \
  -d '{
    "name": "screensanction",
    "dateOfBirth": "1985-03-12",
    "nationality": "AU",
    "schema": "Person",
    "externalReference": "customer-123",
    "listFilter": {
      "topics": ["sanction", "pep"],
      "includeAdverseMedia": false,
      "includeRcas": true
    },
    "minScore": 70
  }'

Response

{
  "screeningRequestId": "uuid",
  "subject": { "name": "Jane Smith", "schema": "Person" },
  "matchCount": 1,
  "cleared": false,
  "matches": [
    {
      "matchId": "uuid",
      "matchType": "list",
      "score": 92,
      "tier": "strong",
      "caption": "Jane Smith",
      "sourceSlugs": ["au_pep_federal"],
      "topics": ["pep"],
      "matchedFields": ["caption"],
      "aliases": [],
      "explanation": {
        "method": ["caption"],
        "sourceCategory": "pep"
      }
    }
  ]
}

Response fields

• cleared - true when no match scored ≥85 (strong/exact threshold)
• matches[].matchType - list, rca, or adverse_media
• matches[].tier - exact, strong, possible, weak
• matches[].relationshipPath - present on RCA hits, shows associate chain
• matches[].article - present on adverse media hits (title, url, publishedAt)

Match tiers

List coverage

VeroID maintains curated sanctions and PEP sources (OFAC, UN, EU, UK, AU Parliament PEP, and others). Sources are crawled on a schedule, QA-reviewed, and published to the matching index. Adverse media checks are opt-in - set listFilter.includeAdverseMedia to true to include them. Published sources are listed in the table below.

Retrieve history

GET /v1/screening              # List recent checks (?limit=20, max 100)
GET /v1/screening/{id}         # Single request with stored matches

Rate limits

Screening endpoints allow 60 requests per minute per API key. When limited, the API returns 429 with a Retry-After header (seconds). See Errors.

Access requirements

MCP integration

The sandbox MCP server exposes screen_subject, list_screening_requests, and get_screening_request. See MCP Server or call get_integration_guide with topic screening.