Supergood | OpenSanctions API
Programmatically access OpenSanctions sanctions lists, politically exposed persons (PEPs), identifiers, aliases, and source metadata with a stable REST API. Supergood builds and operates production-grade, unofficial OpenSanctions integrations so AML/KYC teams can automate screening, ongoing monitoring, and case enrichment without heavy custom engineering.
Plain English: OpenSanctions is an open, aggregated database of sanctions lists, PEPs, crime and corruption data pulled from official and public sources worldwide. An unofficial API lets you programmatically pull deduplicated entities (people and organizations), sanctions entries, PEP roles, aliases, identifiers, relationships, and dataset/source updates—and push screening jobs, internal watchlist entries, and case notes back into your systems.
For a tech company integrating with OpenSanctions, this means you can ingest up-to-date watchlist data to power onboarding screening, run batch checks across your customer base, monitor changes that impact risk, enrich investigations with source-level context, and keep downstream systems (case management, onboarding, CRM, data warehouse) synchronized. You can trigger rescreening, attach evidence to cases, maintain internal watchlists, and feed normalized hits—with match scores and reasons—into adjudication workflows.
What is OpenSanctions?
OpenSanctions (https://www.opensanctions.org/) aggregates and normalizes watchlist data from governments, international bodies, and reputable public sources. The platform harmonizes names, aliases, identifiers, and relationships using the FollowTheMoney-style schema so you can reason across sanctions programs and PEP datasets with consistent structures.
Core product areas include:
- Global Sanctions Aggregation (UN, OFAC, EU, UK, and national lists)
- Politically Exposed Persons (PEPs), officeholders, and public officials
- Crime/Corruption and Law Enforcement Lists (wanted, debarments)
- Entities and Relationships (persons, organizations, officers, associates)
- Aliases, Identifiers, and Addresses (DOB, passports, registration numbers)
- Source/Dataset Metadata (authority, update cadence, provenance)
- Updates and Change Tracking (listings, removals, sanctions status changes)
Common data entities:
- Entities (Person, Organization)
- Sanction Entries (program, authority, status, listing/removal dates)
- PEP Roles/Positions (office, jurisdiction, start/end dates)
- Aliases (name variants, transliterations)
- Identifiers (passport, national ID, company numbers, tax IDs)
- Addresses (location, country, postal data)
- Datasets/Sources (issuer, category, update schedule)
- Relationships (director-of, associated-with, beneficial-owner)
The OpenSanctions Integration Challenge
AML/KYC teams depend on timely watchlist data, but turning web-centric exploration into API-driven automation is non-trivial:
- Name matching complexity: multiple scripts, transliterations, and alias variants
- Entity resolution: deduplication across overlapping sources and jurisdictions
- Update cadence: frequent changes to sanctions and PEP roles require reliable polling/monitoring
- Schema nuance: identifiers, relationships, and roles differ across authorities
- Filtering: per-jurisdiction datasets and program-specific scoping for compliance
- Authentication and licensing: handling keys, sessions, and data usage constraints for production automation
How Supergood Creates OpenSanctions APIs
Supergood reverse-engineers authenticated browser flows and network interactions to deliver a resilient API endpoint layer for OpenSanctions.
- Handles API keys or account credentials securely, including session continuity
- Maintains health checks and automated refresh with change detection for updates
- Normalizes responses so you can integrate once and rely on consistent objects (entities, sanctions, PEP roles, sources)
- Aligns with customer entitlements and licensing to ensure compliant access and usage
- Provides opinionated matching scores and reasons to streamline adjudication workflows
Use Cases
Onboarding Screening
- Screen new customers and counterparties at account opening
- Normalize hits with aliases, identifiers, and jurisdictions
- Log screening jobs with match scores and reasons for audit
Ongoing Monitoring
- Rescreen portfolios and trigger case updates when sanctions change
- Subscribe to updates for specific datasets or jurisdictions
- Drive SLA alerts for new listings, removals, and status changes
Case Management & Escalations
- Enrich investigations with source metadata and relationships
- Attach evidence, internal watchlist entries, and analyst notes
- Push adjudication outcomes back into downstream systems
Analytics & Compliance Reporting
- Build dashboards for exposure by jurisdiction, program, and dataset
- Track throughput, hit rates, and resolution times across teams
- Export normalized entities for model training and QA
Available Endpoints
Authentication
POST /sessions: Establish a session using an API key or credentials. Supergood manages session lifecycles and secure storage. Returns a short-lived auth token maintained by the platform.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/sessions \
--header 'Authorization: Basic <Base64 encoded token>' \
--header 'Content-Type: application/json' \
--data '{
"apiKey": "os_live_3d8c...",
"account": {
"email": "[email protected]",
"mfa": { "type": "totp", "code": "123456" }
}
}'
Example response
{
"authToken": "eyJhbGciOi...",
"expiresIn": 3600,
"entitlements": ["entities", "screenings", "watchlists", "datasets"]
}
Entities
GET /entities: Search and list entities (persons and organizations) with filters, match scoring, and dataset scoping.
Query parameters
- query: string (name or alias)
- schema: person | organization
- datasets: array of dataset keys (e.g., ["sanctions", "peps"])
- country: ISO 3166-1 alpha-2 country code
- birthDateFrom, birthDateTo: ISO dates (person schema)
- updatedFrom, updatedTo: ISO 8601 timestamps
- minScore: number (0–1) minimum match score
- page, pageSize: integers for pagination
Example response
{
"items": [
{
"entityId": "os_ent_9c21f0",
"schema": "person",
"name": "Aleksandr Petrov",
"aliases": ["Alexander Petrov", "Александр Петров"],
"birthDate": "1979-07-15",
"nationalities": ["RU"],
"identifiers": [
{"type": "passport", "value": "71N1234567"},
{"type": "national_id", "value": "RU-19790715-XYZ"}
],
"addresses": [
{"country": "RU", "city": "Moscow"}
],
"sanctions": [
{
"program": "EU-Russia",
"authority": "European Union",
"status": "listed",
"listedAt": "2022-03-01",
"reference": "EU-2022-98"
}
],
"pepRoles": [],
"datasets": ["sanctions/eu", "sanctions/uk"],
"matchScore": 0.93,
"updatedAt": "2026-01-20T13:45:00Z"
}
],
"page": 1,
"pageSize": 50,
"total": 1
}
Screenings
POST /screenings: Create a screening job with candidate details, dataset scope, and matching parameters. Returns summary with hits and risk classification.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/screenings \
--header 'Authorization: Bearer <authToken>' \
--header 'Content-Type: application/json' \
--data '{
"candidate": {
"schema": "person",
"name": "Aleksandr Petrov",
"birthDate": "1979-07-15",
"nationalities": ["RU"],
"identifiers": [
{"type": "passport", "value": "71N1234567"}
]
},
"datasets": ["sanctions", "peps"],
"minScore": 0.85,
"fuzzy": true,
"monitor": true,
"referenceId": "kyc-app-2981"
}'
Example response
{
"screeningId": "scr_51af80",
"status": "completed",
"matchCount": 1,
"riskLevel": "high",
"matches": [
{
"entityId": "os_ent_9c21f0",
"name": "Aleksandr Petrov",
"matchScore": 0.93,
"datasets": ["sanctions/eu", "sanctions/uk"],
"reasons": ["name_alias_match", "identifier_partial_match"],
"sanctions": [
{"program": "EU-Russia", "status": "listed", "listedAt": "2022-03-01"}
]
}
],
"createdAt": "2026-01-21T11:20:44Z"
}
Watchlists
POST /watchlists: Create or add entries to your internal watchlist for custom risk flags, with identifiers and source notes.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/watchlists \
--header 'Authorization: Bearer <authToken>' \
--header 'Content-Type: application/json' \
--data '{
"type": "organization",
"name": "Northlake Trading LLC",
"jurisdiction": "US",
"riskLevel": "medium",
"reasonCode": "adverse_media",
"identifiers": [
{"type": "ein", "value": "12-3456789"}
],
"notes": "Multiple negative media mentions; pending enhanced due diligence.",
"referenceId": "case-4412"
}'
Example response
{
"watchlistId": "wl_90e412",
"status": "active",
"createdAt": "2026-01-21T10:03:11Z"
}
Datasets & Sources
GET /datasets: List available datasets and sources with update cadence and last refresh timestamps.
Query parameters
- category: sanctions | peps | crime | all
- jurisdiction: ISO 3166-1 alpha-2 country code
Example response
{
"items": [
{
"datasetId": "sanctions/eu",
"name": "EU Consolidated Sanctions List",
"category": "sanctions",
"authority": "European Union",
"updateFrequency": "daily",
"lastUpdatedAt": "2026-01-22T08:15:12Z",
"recordCount": 9351
},
{
"datasetId": "peps/global",
"name": "Global PEPs and Officeholders",
"category": "peps",
"authority": "Aggregated Public Sources",
"updateFrequency": "weekly",
"lastUpdatedAt": "2026-01-20T12:00:00Z",
"recordCount": 124553
}
],
"total": 2
}
Technical Specifications
- Authentication: API key or username/password with optional MFA (TOTP); supports service accounts or customer-managed credentials
- Response format: JSON with consistent schemas (entities, sanctions, PEP roles, datasets) and pagination across modules
- Rate limits: Tuned for enterprise throughput while honoring licensing, entitlements, and usage controls
- Session management: Automatic token refresh and session rotation with health checks
- Data freshness: Near real-time retrieval of entities and frequent polling for dataset updates
- Security: Encrypted transport, scoped tokens, and audit logging; respects licensing and access constraints
- Webhooks: Optional asynchronous delivery for long-running workflows (e.g., monitoring hits, dataset refresh events)
Performance Characteristics
- Latency: Sub-second responses for list/detail queries under normal load
- Throughput: Designed for high-volume batch screening and portfolio rescreening
- Reliability: Retry logic, backoff, and idempotency keys minimize duplicate actions and transient errors
- Adaptation: Continuous monitoring for UI/API changes with rapid adapter updates
Getting Started
- Schedule Integration Assessment
Book a 30-minute session to confirm your datasets, licensing, and authentication model.
- Supergood Builds and Validates Your API
We deliver a hardened OpenSanctions adapter tailored to your workflows and entitlements.
- Deploy with Monitoring
Go live with continuous monitoring and automatic adjustments as OpenSanctions evolves.
Frequently Asked Questions
Q: Which OpenSanctions modules can this integration cover?
Supergood supports workflows across core areas such as Sanctions (UN, EU, OFAC, UK, national lists), PEPs/officeholders, identifiers/aliases, relationships, and dataset/source metadata—subject to your licensing and entitlements. We scope coverage during integration assessment.
Q: How do you handle name matching and false positives?
We provide configurable matching thresholds, fuzzy matching, alias handling, and identifier cross-checks. Responses include match scores and reasons so analysts can adjudicate efficiently. We can incorporate your internal heuristics or blocklists.
Q: Can we enable ongoing monitoring and receive alerts?
Yes. We support monitoring flags on screenings and deliver updates via webhooks or polling when entities or datasets change (e.g., new listings, removals, status updates). Alert payloads include entity context and source metadata.
Q: What about licensing and compliance?
We operate within your licensed access and usage constraints, respect OpenSanctions data terms, and provide audit logs for screenings and updates. Coverage and throughput are tuned to your compliance requirements.
Related Integrations
ComplyAdvantage API - Programmatically access ComplyAdvantage with Supergood
Ready to automate your OpenSanctions workflows?
Supergood can have your OpenSanctions integration live in days with no ongoing engineering maintenance.
