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

Category	What it checks	Example matches
PEP	Politically Exposed Persons	Heads of state, senior government officials, their family and associates
Sanctions	Global sanctions lists	OFAC SDN, EU Consolidated, UN Security Council, UK HMT
Adverse Media	Negative news coverage	Financial crime, fraud, terrorism financing, money laundering
Watchlist	Law enforcement databases	Interpol, 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.

Score	Confidence	Recommended action
90-100	Very High	Strong match. Investigate immediately.
80-89	High	Likely match. Manual review required.
70-79	Medium	Possible match. Review recommended, especially with other risk factors.
Below 70	Low	Weak 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.

Class	Description	Examples
`pep-class-1`	Heads of state and senior national government	Presidents, prime ministers, cabinet ministers, supreme court justices
`pep-class-2`	Regional and legislative officials	Members of parliament, senators, governors, mayors of major cities
`pep-class-3`	Other public officials	Senior military officers, central bank board members, ambassadors, judiciary
`pep-class-4`	Associates and family members	Spouses, 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

List	Source	Jurisdiction
`sanction-sdn`	OFAC Specially Designated Nationals	United States
`sanction-eu`	EU Consolidated Sanctions List	European Union
`sanction-un`	UN Security Council Consolidated List	International
`sanction-hmt`	HM Treasury Consolidated List	United 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

Category	Score	Action
Sanctions	Any score	Immediate escalation. Do not proceed with onboarding.
Watchlist	Any score	Immediate escalation. Do not proceed with onboarding.
PEP Class 1-2	80+	Enhanced due diligence required. Senior compliance review.
PEP Class 1-2	70-79	Standard review. Verify match relevance.
PEP Class 3-4	80+	Standard review with ongoing monitoring.
PEP Class 3-4	70-79	Log and monitor. Review if combined with other risk factors.
Adverse Media	85+	Manual review required. Assess severity and recency of media.
Adverse Media	70-84	Review if combined with other risk factors (high-risk jurisdiction, complex ownership).
Adverse Media	Below 70	Log 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:

Immediately halt all processing and onboarding.
Do not auto-approve under any circumstances, regardless of other check results.
Escalate to your compliance team and legal counsel.
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

Getting Started

Use-Case Guides

Platform Concepts

Domain Concepts

Data Model

Screening

Screening

Screening categories

Screen a person

Screen a company

Clean result (no matches)

Result with matches

Match score interpretation

PEP classifications

Sanctions list types

Match management decision matrix

Sanctions halt logic

Screening within Company and Person Verification

Next steps

Sync vs Async

Webhooks Guide

Error Handling

​Screening

​Screening categories

​Screen a person

​Screen a company

​Clean result (no matches)

​Result with matches

​Match score interpretation

​PEP classifications

​Sanctions list types

​Match management decision matrix

​Sanctions halt logic

​Screening within Company and Person Verification

​Next steps

Sync vs Async

Webhooks Guide

Error Handling

Screening

Screening categories

Screen a person

Screen a company

Clean result (no matches)

Result with matches

Match score interpretation

PEP classifications

Sanctions list types

Match management decision matrix

Sanctions halt logic

Screening within Company and Person Verification

Next steps