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 and live screening

Standard prepaid pricing applies to developer accounts:

• Developer accounts (API): each live POST /v1/screening check consumes 0.5 credits at standard rates (see public pricing on veroid.com.au), including the first screen of a person. Scheduled re-screens for names on your monitoring list may be included under your account Plan Terms in the dashboard; they do not replace per-request API screening credits. Sandbox screening is free.
• Identity verification deducts 1 credit per live result (Y, N, or D) for developer prepaid accounts

Purchase API credits from Dashboard > Billing.

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 IVS 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)

Idempotency-Key (recommended)

Send an Idempotency-Key header on every POST /v1/screening so retries do not create duplicate screening rows or duplicate live credit charges. Use a unique value per attempted check (for example a UUID, up to 255 characters). Keys are scoped to your account, test or live (from the API key), and this create endpoint, and are retained for 24 hours.

The same key with the same JSON body returns the original 200 response (same screeningRequestId and match payload) and sets Idempotent-Replayed: true. The same key with a different body returns 422 with code IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PARAMS. Concurrent retries with the same key wait on a server lock and converge on one screening check; they return 200, not 409.

See the idempotency reference for all idempotency outcomes across verify and screening create endpoints.

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" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -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)

Optional match detail fields

When VeroID holds extra attributes for a matched entity, they appear as optional fields on each match object (in POST responses, GET /v1/screening/:id, monitoring webhooks, and the dashboard hit view). Omitted fields were not available for that entity.

VeroID does not hold every attribute for every list entry. Photo URLs, unstructured narrative beyond parsed properties, and fields never published by the source are not returned.

Match tiers

List coverage

Published sanctions, PEP, and adverse media lists, with record counts and how often each list is checked, are on the Sources page. Adverse media checks are opt-in - set listFilter.includeAdverseMedia to true to include them.

Retrieve history

GET /v1/screening              # List recent checks (?limit=20, max 100)
GET /v1/screening?externalReference=customer-123  # Exact match on your reference
GET /v1/screening/{id}         # Single request with stored matches

externalReference filters to an exact match on the value you sent in POST /v1/screening, scoped to your account. Combine with limit as needed.

Ongoing monitoring

Developer accounts can enroll names for repeated screening after the onboarding fee is paid. Each name on the live list is re-screened on a schedule you choose: daily, fortnightly, or monthly. If you omit the interval, it defaults to monthly.

Monitoring billing and included re-screens are set out in your Plan Terms in the dashboard. Live POST /v1/screening checks consume 0.5 credits each, including the first screen of a person.

When a run finishes, VeroID posts the result to a webhook URL you configure and signs the delivery. Test keys on the test API can enroll the same predefined test names used for sandbox screening.

POST   /v1/screening/monitoring/subjects
GET    /v1/screening/monitoring/subjects
PATCH  /v1/screening/monitoring/subjects/{id}
DELETE /v1/screening/monitoring/subjects/{id}
PUT    /v1/screening/monitoring/webhook

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.