PEP & Sanctions Screening Guide

This guide walks you through implementing Politically Exposed Persons (PEP) and sanctions screening using the Matchstra API.

Overview

PEP and sanctions screening helps you comply with Anti-Money Laundering (AML) and Know Your Customer (KYC) regulations by identifying individuals and entities that appear on global watchlists.

Use cases:

Customer onboarding for financial institutions
Vendor and supplier due diligence
Real estate transaction screening
Compliance with FINTRAC, OFAC, and other regulators

Quick Example

const response = await fetch('https://api.matchstra.ca/api/Screening/screen', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Vladimir Putin',
    entityType: 'Individual',
    minScore: 80
  })
});

const result = await response.json();

if (result.success && result.data.hasMatch) {
  console.log(`⚠️ Found ${result.data.matchCount} match(es)`);
  console.log(`Highest confidence: ${result.data.highestScore}%`);
} else {
  console.log('✅ No matches found - safe to proceed');
}

Understanding Entity Types

Specify the type of entity you're screening:

Individual

For screening persons (customers, vendors, beneficial owners).

{
  "name": "John Smith",
  "dateOfBirth": "1980-05-15",
  "entityType": "Individual",
  "minScore": 70
}

Organization

For screening companies, NGOs, and other entities.

{
  "name": "ABC Trading Corp",
  "entityType": "Organization",
  "minScore": 75
}

Confidence Scoring

The minScore parameter controls the sensitivity of matching:

Score Range	Recommendation	Use Case
90-100	High confidence	Strict compliance, low false positives
70-89	Balanced	Standard due diligence
50-69	Sensitive	Cast wider net, more review required
Below 50	Very sensitive	Exploratory, many false positives

Recommended: Start with minScore: 70 and adjust based on your risk tolerance.

Date of Birth Matching

Including date of birth significantly improves match accuracy:

{
  "name": "John Smith",
  "dateOfBirth": "1980-05-15T00:00:00Z",
  "entityType": "Individual",
  "minScore": 70
}

Benefits:

Reduces false positives for common names
Increases confidence in positive matches
Helps distinguish between similarly named individuals

Format: ISO 8601 date-time string (e.g., 1980-05-15T00:00:00Z)

Understanding Results

No Matches Found

{
  "success": true,
  "message": "Screening completed successfully",
  "data": {
    "id": 12345,
    "hasMatch": false,
    "matchCount": 0,
    "highestScore": 0,
    "matches": [],
    "remainingRequests": 485
  }
}

Action: Safe to proceed with onboarding/transaction.

Matches Found

{
  "success": true,
  "message": "Screening completed successfully",
  "data": {
    "id": 12346,
    "hasMatch": true,
    "matchCount": 2,
    "highestScore": 95.5,
    "matches": [
      {
        "name": "John A. Smith",
        "score": 95.5,
        "entityType": "Individual",
        "sources": ["OFAC SDN", "UN Sanctions"],
        "dateOfBirth": "1980-05-15",
        "nationality": "US"
      },
      {
        "name": "John Anthony Smith",
        "score": 78.2,
        "entityType": "Individual",
        "sources": ["EU Sanctions"],
        "dateOfBirth": "1980-05-20",
        "nationality": "GB"
      }
    ],
    "remainingRequests": 484
  }
}

Action: Review matches and apply your risk policies.

Match Analysis

Each match includes:

name

The matched entity name from the watchlist.

score

Confidence score (0-100) indicating match strength. Higher = more confident.

entityType

Type of matched entity (Individual or Organization).

sources

Array of data sources where the match was found:

OFAC SDN - US Office of Foreign Assets Control Specially Designated Nationals
UN Sanctions - United Nations Security Council sanctions
EU Sanctions - European Union sanctions
UK Sanctions - UK HM Treasury sanctions
Canadian Sanctions - Global Affairs Canada
Interpol - Interpol wanted persons
PEP - Politically Exposed Persons databases

dateOfBirth

Date of birth from the watchlist (if available).

nationality

Country or nationality of the entity (if available).

Implementation Patterns

Basic Screening Workflow

async function screenPerson(name, dob) {
  const response = await fetch('https://api.matchstra.ca/api/Screening/screen', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.MATCHSTRA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      dateOfBirth: dob,
      entityType: 'Individual',
      minScore: 70
    })
  });

  const result = await response.json();
  
  if (!result.success) {
    throw new Error(`Screening failed: ${result.message}`);
  }

  return result.data;
}

// Usage
const screeningResult = await screenPerson('John Smith', '1980-05-15');

if (screeningResult.hasMatch) {
  console.log('⚠️ MATCHES FOUND - Manual review required');
  
  for (const match of screeningResult.matches) {
    console.log(`- ${match.name} (${match.score}% confidence)`);
    console.log(`  Sources: ${match.sources.join(', ')}`);
  }
} else {
  console.log('✅ No matches - Proceed with onboarding');
}

Risk-Based Decision Logic

function assessRisk(screeningResult) {
  if (!screeningResult.hasMatch) {
    return 'LOW'; // No matches - safe
  }

  const highestScore = screeningResult.highestScore;
  
  if (highestScore >= 90) {
    return 'HIGH'; // Strong match - likely sanctioned
  } else if (highestScore >= 75) {
    return 'MEDIUM'; // Moderate match - needs review
  } else {
    return 'LOW-MEDIUM'; // Weak match - possible false positive
  }
}

// Usage
const risk = assessRisk(screeningResult);

switch (risk) {
  case 'HIGH':
    // Reject application, file SAR/STR
    rejectApplication();
    fileReport();
    break;
  
  case 'MEDIUM':
    // Escalate to compliance team
    escalateToCompliance();
    break;
  
  case 'LOW-MEDIUM':
    // Optional review
    flagForReview();
    break;
  
  case 'LOW':
    // Auto-approve
    approveApplication();
    break;
}

Bulk Screening

For screening multiple entities:

async function bulkScreen(entities) {
  const results = await Promise.all(
    entities.map(entity => 
      fetch('https://api.matchstra.ca/api/Screening/screen', {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.MATCHSTRA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: entity.name,
          dateOfBirth: entity.dob,
          entityType: entity.type,
          minScore: 70
        })
      }).then(r => r.json())
    )
  );

  return results.map((result, index) => ({
    entity: entities[index],
    screening: result.data,
    hasMatch: result.data?.hasMatch || false
  }));
}

// Usage
const entities = [
  { name: 'John Smith', dob: '1980-05-15', type: 'Individual' },
  { name: 'Jane Doe', dob: '1975-08-22', type: 'Individual' },
  { name: 'ABC Corp', type: 'Organization' }
];

const bulkResults = await bulkScreen(entities);
const flagged = bulkResults.filter(r => r.hasMatch);

console.log(`Screened ${entities.length} entities, found ${flagged.length} with matches`);

Rate Limits

Be mindful of rate limits when bulk screening. Consider implementing batching or rate limiting on your end.

Retrieving Past Screenings

List All Screenings

curl -X GET https://api.matchstra.ca/api/Screening/list \
  -H "X-API-Key: your_api_key_here"

Get Specific Screening

curl -X GET https://api.matchstra.ca/api/Screening/12345 \
  -H "X-API-Key: your_api_key_here"

Best Practices

1. Screen at Key Touchpoints

Onboarding: Screen all new customers
Periodic Review: Re-screen existing customers annually
Transaction Monitoring: Screen parties in high-value transactions
Vendor Approval: Screen all new vendors and partners

2. Implement Tiered Thresholds

Use different minScore values based on risk:

const thresholds = {
  highRisk: 85,      // High-value accounts, sensitive industries
  standard: 70,      // Normal customers
  lowRisk: 60        // Low-value, low-risk relationships
};

const minScore = determineRiskCategory(customer) === 'high' 
  ? thresholds.highRisk 
  : thresholds.standard;

3. Document All Decisions

Maintain audit logs of:

Screening requests and results
Risk assessment decisions
Manual review outcomes
Approval/rejection rationale

4. Handle False Positives

Common causes of false positives:

Common names (e.g., "John Smith")
Missing date of birth
Name variations and nicknames
Transliteration differences

Mitigation:

Always include date of birth when available
Implement manual review for borderline scores
Train staff on false positive analysis

5. Stay Updated

Sanctions lists change frequently. Re-screen:

Existing customers annually (minimum)
High-risk customers quarterly
After major geopolitical events

Compliance Considerations

Regulatory Requirements

Different jurisdictions have specific requirements:

Jurisdiction	Regulator	Key Requirement
Canada	FINTRAC	Screen against Canadian sanctions
USA	FinCEN	Screen OFAC SDN list
EU	EBA	Screen EU sanctions lists
UK	FCA	Screen UK HMT lists

Matchstra covers all major lists by default.

Record Keeping

Maintain screening records for:

Canada: 5 years minimum (FINTRAC)
USA: 5 years minimum (FinCEN)
EU: 5 years minimum (AMLD5)

Store:

Request payload (name, DOB, entity type)
Response data (all matches and scores)
Timestamp of screening
API key used
User/system that initiated screening

Error Handling

See the Error Handling guide for comprehensive error scenarios.

Common screening errors:

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "errors": ["Name is required", "EntityType must be 'Individual' or 'Organization'"]
}

Fix: Validate input before submission.

429 Too Many Requests

{
  "success": false,
  "message": "Rate limit exceeded",
  "errors": ["Request quota exhausted"]
}

Fix: Check remainingRequests in responses and implement rate limiting.

Next Steps

Review the API Reference for complete endpoint details
Learn about Error Handling to build robust integrations
Check Rate Limits to optimize your usage
Try the API Explorer to test screening interactively

Overview​

Quick Example​

Understanding Entity Types​

Individual​

Organization​

Confidence Scoring​

Date of Birth Matching​

Understanding Results​

No Matches Found​

Matches Found​

Match Analysis​

name​

score​

entityType​

sources​

dateOfBirth​

nationality​

Implementation Patterns​

Basic Screening Workflow​

Risk-Based Decision Logic​

Bulk Screening​

Retrieving Past Screenings​

List All Screenings​

Get Specific Screening​

Best Practices​

1. Screen at Key Touchpoints​

2. Implement Tiered Thresholds​

3. Document All Decisions​

4. Handle False Positives​

5. Stay Updated​

Compliance Considerations​

Regulatory Requirements​

Record Keeping​

Error Handling​

400 Bad Request​

429 Too Many Requests​

Next Steps​