Skip to main content

​
Screening

Screen individuals and companies against PEP, sanctions, adverse media, and watchlist databases. Screening runs synchronously via WorldCheck and returns structured match results. Screening runs automatically as part of Company and Person Verification flows. Use the standalone screening endpoint for ongoing monitoring, pre-verification checks, or batch processing.

​
Screening categories

CategoryWhat it checksExample matches
PEPPolitically Exposed PersonsHeads of state, senior government officials, their family and associates
SanctionsGlobal sanctions listsOFAC SDN, EU Consolidated, UN Security Council, UK HMT
Adverse MediaNegative news coverageFinancial crime, fraud, terrorism financing, money laundering
WatchlistLaw enforcement databasesInterpol, FBI, national fugitive lists

​
Screen a person

Always include date_of_birth when screening individuals. It is the single most effective field for reducing false positives. Without it, common names like “John Smith” can return hundreds of matches. With it, the result set typically shrinks by 90% or more.
curl -X POST \
  "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/screening/api" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SYNC-TIMEOUT: 30000" \
  -d '{
    "name": "John Smith",
    "date_of_birth": "1975-03-20",
    "country": "GB",
    "entity_type": "person",
    "categories": ["pep", "sanctions", "adverse_media", "watchlist"]
  }'

​
Screen a company

curl -X POST \
  "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/screening/api" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SYNC-TIMEOUT: 30000" \
  -d '{
    "name": "Acme Holdings Ltd",
    "country": "GB",
    "entity_type": "company",
    "categories": ["sanctions", "adverse_media"]
  }'

​
Clean result (no matches)

When an entity has no matches across any category: 
{
  "screening_status": "complete",
  "pep_status": "No Hit",
  "sanctions_status": "No Hit",
  "adverse_media_status": "No Hit",
  "watchlist_status": "No Hit",
  "screening_provider": "WorldCheck",
  "screening_completed_at": "2026-01-15T14:30:00Z",
  "total_matches": 0,
  "matches": []
}
An empty matches array with all status fields showing "No Hit" means the entity does not appear in any screened database.

​
Result with matches

When screening returns hits, each match includes a score, category, and supporting data: 
{
  "screening_status": "complete",
  "pep_status": "Hit",
  "sanctions_status": "No Hit",
  "adverse_media_status": "Hit",
  "watchlist_status": "No Hit",
  "screening_provider": "WorldCheck",
  "screening_completed_at": "2026-01-15T14:30:00Z",
  "total_matches": 2,
  "top_match_score": 95.0,
  "matches": [
    {
      "matchScore": 95.0,
      "matchStrength": "EXACT",
      "primaryName": "John Andrew Smith",
      "category": "pep",
      "categories": ["pep-class-2"],
      "types": ["pep-class-2"],
      "gender": "MALE",
      "nationality": "British",
      "dateOfBirth": "1975-03-20",
      "countries": [
        "United Kingdom (Nationality)",
        "United Kingdom (Location)"
      ],
      "sources": ["UK Parliament", "Companies House"],
      "enteredDate": "2018-04-12",
      "lastUpdated": "2025-11-03",
      "positions": [
        {
          "title": "Member of Parliament",
          "country": "United Kingdom",
          "from": "2019-12-12",
          "to": "2024-07-04"
        }
      ],
      "associates": [
        {
          "name": "Mary Smith",
          "association": "Spouse",
          "type": "family"
        }
      ]
    },
    {
      "matchScore": 78.5,
      "matchStrength": "STRONG",
      "primaryName": "John Smith",
      "category": "adverse_media",
      "categories": ["adverse-media-financial-crime"],
      "types": ["adverse-media"],
      "gender": "MALE",
      "nationality": "British",
      "dateOfBirth": "1975-03-20",
      "countries": ["United Kingdom (Nationality)"],
      "sources": ["Financial Times", "BBC News"],
      "enteredDate": "2025-06-15",
      "lastUpdated": "2025-09-22",
      "media": [
        {
          "title": "Investigation into financial irregularities at Acme Holdings",
          "url": "https://example.com/article-123",
          "snippet": "Authorities are investigating potential financial irregularities...",
          "date": "2025-06-15"
        }
      ]
    }
  ]
}

​
Match score interpretation

Match scores range from 0 to 100 and indicate the confidence that a screened entity matches a database record.
ScoreConfidenceRecommended action
90-100Very HighStrong match. Investigate immediately.
80-89HighLikely match. Manual review required.
70-79MediumPossible match. Review recommended, especially with other risk factors.
Below 70LowWeak match. Likely a false positive, but review if combined with high-risk indicators.
Do not auto-dismiss matches in the 70-79 range. WorldCheck scoring is conservative, and a 75% match on a sanctioned entity still requires investigation.

​
PEP classifications

WorldCheck classifies Politically Exposed Persons into four tiers based on their level of public office.
ClassDescriptionExamples
pep-class-1Heads of state and senior national governmentPresidents, prime ministers, cabinet ministers, supreme court justices
pep-class-2Regional and legislative officialsMembers of parliament, senators, governors, mayors of major cities
pep-class-3Other public officialsSenior military officers, central bank board members, ambassadors, judiciary
pep-class-4Associates and family membersSpouses, children, parents, known business partners of PEP Class 1-3
PEP Class 1 matches must always be escalated to a senior compliance officer regardless of match score. These individuals carry the highest regulatory scrutiny under FATF recommendations.

​
Sanctions list types

ListSourceJurisdiction
sanction-sdnOFAC Specially Designated NationalsUnited States
sanction-euEU Consolidated Sanctions ListEuropean Union
sanction-unUN Security Council Consolidated ListInternational
sanction-hmtHM Treasury Consolidated ListUnited Kingdom
Any sanctions match, regardless of score, must halt onboarding immediately. Processing transactions for sanctioned entities carries severe penalties including criminal prosecution, asset freezes, and regulatory enforcement action.

​
Match management decision matrix

CategoryScoreAction
SanctionsAny scoreImmediate escalation. Do not proceed with onboarding.
WatchlistAny scoreImmediate escalation. Do not proceed with onboarding.
PEP Class 1-280+Enhanced due diligence required. Senior compliance review.
PEP Class 1-270-79Standard review. Verify match relevance.
PEP Class 3-480+Standard review with ongoing monitoring.
PEP Class 3-470-79Log and monitor. Review if combined with other risk factors.
Adverse Media85+Manual review required. Assess severity and recency of media.
Adverse Media70-84Review if combined with other risk factors (high-risk jurisdiction, complex ownership).
Adverse MediaBelow 70Log for audit trail. Likely false positive.

​
Sanctions halt logic

If sanctions_status is "Hit" on any entity, your system must immediately halt all processing. Here is the recommended implementation:
decision-handler.js
function evaluateVerification(result) {
  // Sanctions check is always first, always a hard stop
  if (hasSanctionsHit(result)) {
    return { action: "HALT", reason: "Sanctions hit detected", escalate: true };
  }

  // ... other decision logic
}

function hasSanctionsHit(result) {
  if (result.screening?.sanctions_status === "Hit") return true;

  const entities = [
    ...(result.directors || []),
    ...(result.beneficial_owners || [])
  ];

  return entities.some((e) => e.sanctions_status === "Hit");
}
When a sanctions hit is detected:
  1. Immediately halt all processing and onboarding.
  2. Do not auto-approve under any circumstances, regardless of other check results.
  3. Escalate to your compliance team and legal counsel.
  4. Document the match and your response for regulatory audit purposes.

​
Screening within Company and Person Verification

Screening runs automatically when you submit a Company or Person Verification request. You do not need to call the screening endpoint separately. Results appear in the screening section of the compliance report. Use the standalone screening endpoint for three scenarios: Ongoing monitoring. Re-screen existing customers on a schedule (monthly, quarterly) to catch new PEP appointments, sanctions designations, or adverse media. 
# Re-screen an existing customer
curl -X POST \
  "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/screening/api" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-SYNC-TIMEOUT: 15000" \
  -d '{
    "name": "John Smith",
    "date_of_birth": "1975-03-20",
    "country": "GB",
    "entity_type": "person",
    "categories": ["pep", "sanctions", "adverse_media", "watchlist"],
    "external_reference": "MONITOR-2026-Q1-00042"
  }'
Pre-checks. Screen a name before starting a full Company or Person Verification flow to identify obvious blockers early. Batch screening. Screen multiple entities in sequence without running full verification.

​
Next steps

Sync vs Async

Understand execution models and timeouts

Webhooks Guide

Receive screening results via webhook

Error Handling

Handle provider timeouts and failures