OpenSanctions Getting Started: API Access and First Query (2026)

Getting started overview

Integrating with OpenSanctions for sanctions and watchlist data involves a sequence of steps that enable access to its structured datasets. The process typically begins with account registration, followed by the acquisition of an API key, which serves as the primary method for authenticating requests to the OpenSanctions API. This API is designed as a RESTful interface, allowing for programmatic queries to retrieve entity information, including individuals and organizations listed on various sanctions and politically exposed person (PEP) lists. Data can be consumed directly via the API or through bulk data downloads, depending on the integration requirements and scale of use. The OpenSanctions platform offers a free tier for non-commercial use, alongside paid plans for commercial applications, with detailed API reference documentation available.

The following table outlines the key steps to begin using OpenSanctions:

Create an account and get keys

To begin using the OpenSanctions API, account creation is the foundational step. Navigate to the OpenSanctions homepage and select the option to sign up. During registration, you will typically provide an email address and create a password. Once your account is established, you will gain access to a personal dashboard or account area. Within this dashboard, an API key is provided, which is essential for authenticating all your requests to the OpenSanctions API. This key acts as a unique identifier and authorization token, linking your API calls to your account and usage plan.

The API key is a sensitive credential and should be treated with the same security considerations as other authentication tokens, such as those used for OAuth 2.0 flows. It is recommended to store your API key securely and avoid hardcoding it directly into client-side applications or publicly accessible repositories. For server-side applications, environment variables or secure configuration management systems are appropriate methods for storing and accessing the key. If your API key is compromised, it can usually be revoked and a new one generated from your OpenSanctions account dashboard, as detailed in the OpenSanctions documentation.

Your first request

After obtaining your API key, you can make your first request to the OpenSanctions API. The API is structured around common search and entity retrieval patterns. A typical initial request involves searching for a name to see if it appears on any sanctions or watchlist entries. The OpenSanctions API uses HTTP GET requests for searches, with parameters passed in the query string. Your API key must be included in the request for authentication.

Example: Searching for an entity

Let's consider a search for a common name, for instance, "John Doe". You would typically use the /search endpoint. The API key is usually passed as a header or a query parameter, depending on the specific API version and configuration. For demonstration purposes, we'll assume it's passed as an Authorization header.

Using cURL:

curl -X GET \
  'https://api.opensanctions.org/1.0/search?q=John%20Doe' \
  -H 'Authorization: Apikey YOUR_API_KEY'

Replace YOUR_API_KEY with the actual API key from your OpenSanctions account. The q parameter specifies the search query.

Using Python (with requests library):

import requests

api_key = "YOUR_API_KEY"
query = "John Doe"
url = f"https://api.opensanctions.org/1.0/search?q={query}"
headers = {
    "Authorization": f"Apikey {api_key}"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python script performs the same search. The requests library simplifies HTTP interactions. Ensure you have it installed (pip install requests).

Expected Response Structure:

A successful response (HTTP status code 200) will return a JSON object containing a list of matching entities. Each entity will have various attributes, such as name, schema (e.g., Person, Organization), datasets it appears in, and potentially identifiers or addresses. The exact structure can be found in the OpenSanctions search API documentation.

For example, a simplified response might look like this:

{
  "results": [
    {
      "id": "os-8588079532858178650",
      "schema": "Person",
      "name": "John Doe",
      "birth_date": ["1970-01-01"],
      "countries": ["US"],
      "datasets": ["eu_sanctions", "us_ofac"],
      "properties": {
        "name": ["John Doe"],
        "birthDate": ["1970-01-01"]
      }
    }
  ],
  "limit": 10,
  "offset": 0,
  "total": 1
}

This structure indicates that "John Doe" was found, along with basic identifying information and the datasets where the match occurred. The total field indicates the total number of matches, and limit/offset are for pagination, which is important for handling large result sets.

Common next steps

After successfully making your first API call and understanding the basic response structure, several common next steps can enhance your integration with OpenSanctions:

• Refine Search Queries: Explore advanced search parameters such as fuzzy matching, country filters, and schema filters (e.g., Person or Organization) to narrow down results and improve accuracy. The OpenSanctions search API reference provides a comprehensive list of available parameters.
• Entity Matching Service: For more sophisticated anti-money laundering (AML) and know-your-customer (KYC) processes, investigate the entity matching service. This service can help identify potential matches even with partial or slightly incorrect input data, which is crucial for real-world screening scenarios.
• Bulk Data Downloads: If your application requires frequent access to the entire dataset or a significant portion of it offline, consider utilizing the bulk data download options. Data is available in formats like CSV and JSON, suitable for local processing and integration into custom databases or data lakes.
• Webhooks and Notifications: For staying updated on changes to sanctions lists, explore whether OpenSanctions offers webhook capabilities or other notification mechanisms. This allows your system to react to updates in near real-time, maintaining compliance without constant polling. While specific webhook details are best found in the official OpenSanctions documentation, webhooks are a common pattern for event-driven integrations across many APIs, like those offered by Twilio's webhook security guide.
• Error Handling and Rate Limits: Implement robust error handling in your application to gracefully manage various API responses, including rate limit errors (HTTP 429), authentication failures (HTTP 401), or bad requests (HTTP 400). Understand the API rate limits applicable to your subscription tier to avoid service interruptions.
• Integration with Existing Systems: Plan how to integrate the retrieved sanctions data into your existing compliance, CRM, or ERP systems. This might involve developing adapters or using integration platforms as a service (iPaaS) like Tray.io's integration platform.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to troubleshooting typical problems:

• Invalid API Key (HTTP 401 Unauthorized):
  • Issue: The most frequent cause is an incorrect or missing API key.
  • Solution: Double-check that your API key is correctly copied from your OpenSanctions account dashboard. Ensure it's included in the Authorization header or as a query parameter exactly as specified in the OpenSanctions API documentation. Verify there are no extra spaces or characters.
• Bad Request (HTTP 400):
  • Issue: This usually indicates a problem with your request parameters, such as missing required fields or incorrectly formatted values.
  • Solution: Review the API endpoint documentation for the specific parameters you are using. Ensure all required parameters are present and that their values conform to the expected data types and formats (e.g., correct date format, valid country codes).
• Not Found (HTTP 404):
  • Issue: The requested endpoint or resource does not exist.
  • Solution: Verify the API endpoint URL. Ensure there are no typos in the base URL (e.g., api.opensanctions.org) or the path (e.g., /1.0/search).
• Rate Limit Exceeded (HTTP 429 Too Many Requests):
  • Issue: You've sent too many requests in a given time frame, exceeding your plan's rate limits.
  • Solution: Implement exponential backoff or another rate-limiting strategy in your application. Check your OpenSanctions account or documentation for specific rate limit details and consider upgrading your plan if sustained higher throughput is needed.
• Server Error (HTTP 5xx):
  • Issue: A problem occurred on the OpenSanctions server.
  • Solution: These errors are typically outside your control. Wait a few moments and retry the request. If the issue persists, check the OpenSanctions status page (if available) or contact their support team.
• Network Connectivity Issues:
  • Issue: Your client cannot reach the OpenSanctions API server.
  • Solution: Verify your internet connection. Check for any firewall rules or proxy settings that might be blocking outbound requests from your development environment.