Services

Copy page

Risk & Compliance

Screen individuals and businesses against global sanctions lists, PEP databases, and adverse media sources for AML/CFT compliance.

Overview

The Risk & Compliance service provides comprehensive screening capabilities aligned with Botswana FIA (Financial Intelligence Agency) AML/CFT guidelines. Screen against 200+ global sanctions lists, identify Politically Exposed Persons (PEPs), scan for adverse media coverage, and calculate unified risk scores.

Base Path: /v1/sanctions

Key Features

• Screen against UN, EU, OFAC, UK, and 200+ global sanctions lists
• Politically Exposed Persons (PEP) identification
• Real-time adverse media screening via Google Search grounding
• AI-powered risk scoring per Botswana FIA guidelines
• Support for both individual and business entity screening
• Fuzzy name matching with configurable thresholds

---

API Endpoints

Sanctions Screen - Basic Screening

Screen a name against global sanctions and PEP databases. Returns raw matches.

Endpoint: POST /v1/sanctions/screen

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/sanctions/screen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "birthDate": "1990-01-15",
    "country": "BW",
    "entityType": "PERSON"
  }'

Request Body:

Field	Type	Required	Description
name	string	✅	Full name of individual or business
birthDate	string	❌	Date of birth (YYYY-MM-DD) for better matching
country	string	❌	ISO country code (e.g., "BW")
entityType	string	❌	"PERSON" or "BUSINESS"

Response:

Code
 
{
  "query": "John Doe",
  "totalMatches": 2,
  "matches": [
    {
      "name": "John Doe",
      "score": 95.5,
      "source": "UN Sanctions List",
      "listType": "SANCTIONS",
      "details": {
        "aliases": ["J. Doe"],
        "nationality": "Unknown",
        "dateOfBirth": "1990-01-15",
        "listedOn": "2023-06-15",
        "reason": "Associated with money laundering"
      }
    }
  ],
  "timestamp": "2026-02-06T10:30:00Z"
}

---

Enhanced Screening - Consolidated Results

Enhanced screening with duplicate consolidation and optional AI enrichment via Gemini.

Endpoint: POST /v1/sanctions/screen/enhanced

Query Parameters:

Param	Type	Default	Description
useAi	boolean	true	Enable Gemini AI enrichment for better context

Request:

Code
 
curl -X POST "https://api.botskyc.com/v1/sanctions/screen/enhanced?useAi=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "country": "BW",
    "entityType": "PERSON"
  }'

Response:

Code
 
{
  "query": "John Doe",
  "totalMatches": 1,
  "consolidatedMatches": [
    {
      "name": "John Doe",
      "score": 95.5,
      "sources": ["UN Sanctions List", "EU Consolidated List"],
      "listTypes": ["SANCTIONS"],
      "aiSummary": "Individual listed on multiple sanctions lists for alleged involvement in financial crimes. Listed since 2023.",
      "riskLevel": "HIGH",
      "details": {
        "aliases": ["J. Doe", "Jonathan Doe"],
        "nationality": "Unknown",
        "dateOfBirth": "1990-01-15"
      }
    }
  ],
  "timestamp": "2026-02-06T10:30:00Z"
}

Key Differences from Basic Screening:

• Consolidates duplicate matches across lists
• Provides AI-generated summary and risk assessment
• Better false positive reduction

---

Adverse Media Screening

Screen for negative media coverage using Google Search grounding via Gemini AI.

Endpoint: POST /v1/sanctions/screen/adverse-media

Request:

Code
 
curl -X POST https://api.botskyc.com/v1/sanctions/screen/adverse-media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "country": "BW"
  }'

Response:

Code
 
{
  "query": "John Doe",
  "hasAdverseMedia": true,
  "riskLevel": "MEDIUM",
  "articles": [
    {
      "title": "Local businessman linked to fraud investigation",
      "source": "Botswana Gazette",
      "date": "2025-08-15",
      "url": "https://example.com/article",
      "summary": "John Doe was mentioned in connection with a fraud investigation...",
      "sentiment": "NEGATIVE",
      "categories": ["FRAUD", "FINANCIAL_CRIME"]
    }
  ],
  "aiAnalysis": "Based on available media coverage, the subject has been mentioned in 2 negative articles related to financial misconduct.",
  "timestamp": "2026-02-06T10:30:00Z"
}

Media Categories Detected:

• Financial Crime & Fraud
• Money Laundering
• Corruption & Bribery
• Terrorism & Violent Crime
• Regulatory Actions
• Environmental Violations

---

Risk Score - AI Risk Assessment

Calculate a comprehensive risk score combining sanctions, PEP status, and adverse media per Botswana FIA AML/CFT guidelines.

Endpoint: POST /v1/sanctions/risk-score

Query Parameters:

Param	Type	Default	Description
includeAdverseMedia	boolean	true	Include adverse media in risk calculation

Request:

Code
 
curl -X POST "https://api.botskyc.com/v1/sanctions/risk-score?includeAdverseMedia=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "birthDate": "1990-01-15",
    "country": "BW",
    "entityType": "PERSON"
  }'

Response:

Code
 
{
  "query": "John Doe",
  "overallRiskScore": 35,
  "riskLevel": "MEDIUM",
  "decision": "MANUAL_REVIEW",
  "components": {
    "sanctionsScore": 0,
    "pepScore": 20,
    "adverseMediaScore": 15,
    "countryRiskScore": 0
  },
  "sanctionsMatches": 0,
  "pepMatches": 1,
  "adverseMediaFound": true,
  "recommendations": [
    "Enhanced due diligence recommended due to PEP status",
    "Review adverse media articles for relevance"
  ],
  "fiaCompliance": {
    "guideline": "FIA AML/CFT Risk Assessment Framework",
    "riskCategory": "Medium Risk Customer",
    "requiredActions": ["Enhanced CDD", "Ongoing monitoring"]
  },
  "timestamp": "2026-02-06T10:30:00Z"
}

Risk Score Ranges:

Score	Level	Decision	Action
0-20	LOW	APPROVE	Standard due diligence
21-50	MEDIUM	MANUAL_REVIEW	Enhanced due diligence
51-80	HIGH	ESCALATE	Senior review required
81-100	CRITICAL	REJECT	Automatic rejection

---

Complete Screening Workflow

Code
 
async function screenCustomer(customerData) {
  const apiKey = process.env.BOTSKYC_API_KEY;
  const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  };

  // Step 1: Get comprehensive risk score
  const riskResponse = await fetch(
    'https://api.botskyc.com/v1/sanctions/risk-score?includeAdverseMedia=true',
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: customerData.fullName,
        birthDate: customerData.dateOfBirth,
        country: 'BW',
        entityType: 'PERSON'
      })
    }
  );

  const riskResult = await riskResponse.json();

  // Step 2: Take action based on risk level
  switch (riskResult.decision) {
    case 'APPROVE':
      return { approved: true, message: 'Low risk - proceed with onboarding' };

    case 'MANUAL_REVIEW':
      // Step 3: Get detailed screening for review
      const enhancedResponse = await fetch(
        'https://api.botskyc.com/v1/sanctions/screen/enhanced',
        { method: 'POST', headers, body: JSON.stringify({ name: customerData.fullName }) }
      );
      const enhanced = await enhancedResponse.json();
      return { approved: false, review: true, details: enhanced };

    case 'ESCALATE':
    case 'REJECT':
      return { approved: false, blocked: true, riskScore: riskResult.overallRiskScore };
  }
}

---

Best Practices

Screening Strategy

• Screen at onboarding - Always screen new customers before account creation
• Ongoing monitoring - Re-screen existing customers periodically (monthly/quarterly)
• Event-driven screening - Re-screen when customer data changes
• Batch screening - Use enhanced screening for bulk processing

Reducing False Positives

• Include date of birth - Significantly improves matching accuracy
• Use country code - Helps disambiguate common names
• Use enhanced screening - AI consolidation reduces duplicates
• Set entity type - Distinguishes individuals from businesses

Compliance Requirements

Per Botswana FIA guidelines:

• Screen all customers against sanctions lists before onboarding
• Document all screening results and decisions
• Retain screening records for minimum 5 years
• Report suspicious transactions to FIA within 24 hours
• Implement ongoing monitoring for high-risk customers

---

Integration Examples

Python

Code
 
import requests
import os

def screen_customer(name, birth_date=None, country='BW'):
    api_key = os.getenv('BOTSKYC_API_KEY')

    payload = {
        'name': name,
        'country': country,
        'entityType': 'PERSON'
    }
    if birth_date:
        payload['birthDate'] = birth_date

    response = requests.post(
        'https://api.botskyc.com/v1/sanctions/risk-score',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json=payload
    )

    response.raise_for_status()
    result = response.json()

    print(f"Risk Score: {result['overallRiskScore']}")
    print(f"Risk Level: {result['riskLevel']}")
    print(f"Decision: {result['decision']}")

    return result

# Usage
result = screen_customer('John Doe', '1990-01-15')

---

Error Codes

Code	Status	Message	Resolution
200	Success	Screening completed	-
400	Bad Request	Missing name parameter	Include name in request body
401	Unauthorized	Invalid API key	Check your API key
429	Too Many Requests	Rate limit exceeded	Implement backoff strategy
500	Server Error	Screening service error	Contact support
503	Unavailable	AI service unavailable	Retry without AI enrichment

---

Pricing

Service	Price per Request
Basic Screening	BWP 3-5
Enhanced Screening	BWP 5-8
Adverse Media	BWP 5-8
Risk Score	BWP 8-12

Volume discounts available. Contact [email protected].

---

Support

• Email: [email protected]
• API Reference: Full API Docs
• FIA Guidelines: Botswana FIA

---

Related Documentation:

• Business Verification
• Document Forensics
• Error Handling