OpenSanctions

Supergood | OpenSanctions API

Alex Klarfeld

Alex Klarfeld

— 6 min read
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
}

Get full API Specs →

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

  1. Schedule Integration Assessment

Book a 30-minute session to confirm your datasets, licensing, and authentication model.

  1. Supergood Builds and Validates Your API

We deliver a hardened OpenSanctions adapter tailored to your workflows and entitlements.

  1. Deploy with Monitoring

Go live with continuous monitoring and automatic adjustments as OpenSanctions evolves.

Schedule Integration Call →

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.

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.

Get Started →

Read more