Python SDK

The official Python SDK for SanctionsWise API.

---

Installation

pip install sanctionswise

Requirements:

• Python 3.8 or higher
• requests library (installed automatically)

---

Quick Start

from sanctionswise import SanctionsWiseClient

# Initialize client
client = SanctionsWiseClient(api_key="your-api-key")

# Screen an entity
result = client.screen_entity(
    name="John Smith",
    entity_type="individual"
)

print(f"Status: {result.status}")
print(f"Matches: {len(result.matches)}")

---

Configuration

API Key

# Option 1: Pass directly
client = SanctionsWiseClient(api_key="your-api-key")

# Option 2: Environment variable
# export SANCTIONSWISE_API_KEY=your-api-key
client = SanctionsWiseClient()

# Option 3: Configuration file
client = SanctionsWiseClient.from_config("~/.sanctionswise/config.json")

Options

client = SanctionsWiseClient(
    api_key="your-api-key",
    base_url="https://api.orchestraprime.ai/sanctionswise",  # Default
    timeout=30,          # Request timeout in seconds
    max_retries=3,       # Retry attempts for transient errors
    retry_delay=1.0,     # Initial retry delay in seconds
)

---

Screening Methods

Single Entity

result = client.screen_entity(
    name="John Smith",
    entity_type="individual",  # individual, organization, vessel
    lists=["all"],             # or ["ofac_sdn", "bis_entity"]
    threshold=0.85,            # Minimum match score
    include_semantic=True      # Enable AI matching (Pro+)
)

# Access results
print(result.status)        # clear, match, potential_match
print(result.matches)       # List of Match objects
print(result.audit_token)   # For compliance records

Batch Screening

entities = [
    {"name": "Entity One", "entity_type": "individual"},
    {"name": "Entity Two", "entity_type": "organization"},
    {"name": "Entity Three", "entity_type": "individual"},
]

results = client.screen_batch(
    entities=entities,
    lists=["all"],
    threshold=0.85
)

for result in results:
    print(f"{result.name}: {result.status}")

Large List Processing

def process_large_list(entities, batch_size=100):
    """Process lists larger than 100 entities."""
    all_results = []

    for i in range(0, len(entities), batch_size):
        batch = entities[i:i + batch_size]
        results = client.screen_batch(entities=batch)
        all_results.extend(results)

        # Respect rate limits
        time.sleep(0.1)

    return all_results

---

Entity Lookup

# Get entity details by ID
entity = client.get_entity("sdn_12345")

print(entity.name)
print(entity.aliases)
print(entity.identifiers)
print(entity.addresses)
print(entity.programs)

---

List Operations

# Get all available lists
lists = client.get_lists()

for lst in lists:
    print(f"{lst.list_id}: {lst.entity_count} entities")

# Get specific list details
sdn = client.get_list("ofac_sdn")
print(f"Last updated: {sdn.last_updated}")

---

Response Objects

ScreeningResult

@dataclass
class ScreeningResult:
    status: str              # clear, match, potential_match
    matches: List[Match]     # List of matches
    audit_token: str         # Audit trail token
    data_freshness: dict     # List update timestamps
    request_id: str          # Request tracking ID

Match

@dataclass
class Match:
    entity_id: str           # Sanctioned entity ID
    name: str                # Entity name
    score: float             # Match confidence (0-1)
    match_types: List[str]   # exact, fuzzy, phonetic, semantic
    list_id: str             # Source list
    programs: List[str]      # Sanction programs
    source: SourceInfo       # Authority details

---

Error Handling

from sanctionswise.exceptions import (
    SanctionsWiseError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    ServerError
)

try:
    result = client.screen_entity(name="Test")

except AuthenticationError:
    # Invalid or expired API key
    print("Check your API key")

except RateLimitError as e:
    # Rate limit exceeded
    print(f"Retry after {e.retry_after} seconds")
    time.sleep(e.retry_after)
    # Retry request

except ValidationError as e:
    # Invalid request parameters
    print(f"Validation error: {e.message}")
    print(f"Field: {e.field}")

except ServerError:
    # Server-side error
    print("Service temporarily unavailable")

except SanctionsWiseError as e:
    # Any other API error
    print(f"Error: {e}")

---

Async Support

import asyncio
from sanctionswise import AsyncSanctionsWiseClient

async def main():
    client = AsyncSanctionsWiseClient(api_key="your-api-key")

    # Async screening
    result = await client.screen_entity(
        name="John Smith",
        entity_type="individual"
    )

    # Concurrent batch processing
    tasks = [
        client.screen_entity(name=name)
        for name in ["Entity 1", "Entity 2", "Entity 3"]
    ]
    results = await asyncio.gather(*tasks)

    await client.close()

asyncio.run(main())

---

Logging

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Or configure specific logger
logger = logging.getLogger("sanctionswise")
logger.setLevel(logging.DEBUG)

---

Type Hints

The SDK includes complete type hints for IDE support:

from sanctionswise import SanctionsWiseClient
from sanctionswise.types import (
    ScreeningRequest,
    ScreeningResult,
    EntityType,
    ListId
)

def screen_customer(name: str) -> ScreeningResult:
    client = SanctionsWiseClient()
    return client.screen_entity(
        name=name,
        entity_type=EntityType.INDIVIDUAL
    )

---

Complete Example

"""Complete sanctions screening workflow."""

from sanctionswise import SanctionsWiseClient
from sanctionswise.exceptions import RateLimitError
import time

def screen_customers(customers: list) -> dict:
    """Screen a list of customers against sanctions lists."""

    client = SanctionsWiseClient()
    results = {"clear": [], "matches": [], "errors": []}

    for customer in customers:
        try:
            result = client.screen_entity(
                name=customer["name"],
                entity_type=customer.get("type", "individual"),
                threshold=0.85
            )

            if result.status == "clear":
                results["clear"].append({
                    "customer": customer,
                    "audit_token": result.audit_token
                })
            else:
                results["matches"].append({
                    "customer": customer,
                    "matches": result.matches,
                    "audit_token": result.audit_token
                })

        except RateLimitError as e:
            time.sleep(e.retry_after)
            # Retry logic here

        except Exception as e:
            results["errors"].append({
                "customer": customer,
                "error": str(e)
            })

    return results


if __name__ == "__main__":
    customers = [
        {"name": "John Smith", "type": "individual"},
        {"name": "Acme Corp", "type": "organization"},
    ]

    results = screen_customers(customers)
    print(f"Clear: {len(results['clear'])}")
    print(f"Matches: {len(results['matches'])}")

---

Resources

• API Reference
• Best Practices
• Error Handling Guide
• GitHub Repository

---

SanctionsWise API is a product of OrchestraPrime LLC