RiskIntel

RiskIntel API

The OpenSancton API (version 1) provides programmatic access to OpenSancton's risk intelligence platform. The API is organized around RESTful HTTP endpoints and supports real-time entity analysis, web data intelligence, sanctions screening, and relationship mapping.

You can generate or request an OpenAPI schema (YAML/JSON) of the OpenSancton API. The backend source code is available on request via GitHub (private).

All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding, unless stated otherwise.

To access the API via Node.js, you can use the built-in HTTP module or third-party clients like axios.

To access the API via Python, use requests or integrate with tools like FastAPI SDKs. The request parameters and functions correspond to the API endpoints, making it easy to automate workflows or integrations.

Note

All JSON requests must include the headerContent-Type: application/json. API endpoints also support an optionalmethodquery parameter for overriding the HTTP method if needed (e.g., call a POST endpoint using a GET request by adding?method=POST).

Authentication (Optional for now)

Your API token is available in the OpenSancton Console under your user profile or integrations page.

Use your token in one of the following ways:

Header (Recommended): Authorization: Bearer <your_token>
Query Parameter (Less secure): ?token=<your_token>

Warning

Avoid sharing your API token or password with untrusted parties. Tokens passed as query parameters may be logged in browser history or server logs.

POST

Basic Usage

To perform a risk assessment, send a POST request to: POST /api/v2/check
This endpoint accepts multiple types of payloads for entity/person/company checks. Below are valid request payload examples:

Example URL: https://riskintelapi.cloudastra.co/api/v2/check

POST /api/v2/check

Request Payload Example 1 (Person):

A minimal payload for checking a person entity.

Request Payload (Person)

{
  "entity": {
    "name": "john doe",
    "type": "person",
    "alias": [
      "JD",
      "Jonathan"
    ],
    "gender": "male",
    "dateOfBirth": "15 April 1XXX0"
  }
}

Request Payload Example 2 (Company):

A minimal payload for checking a company entity.

Request Payload (Company)

{
  "entity": {
    "name": "alpha corp",
    "type": "company",
    "alias": [
      "Alpha XXXXTechnologiesXXXLtd.",
      "Альфа Технолоджис ООО"
    ],
    "country": "us",
    "registration_number": "9988776XXX55",
    "tax_number": "1234567XXX0",
    "program": "US-AB1XXX01"
  }
}

Request Payload Example 3 (Company + Person):

A payload for checking both a company and a person in a single request.

Note

Request Payload (Company + Person)

{
  "company": {
    "name": "zeon enterprises",
    "address": "456 Tech Valley, Silicon XXXXCity",
    "phone": "+1-800-555-9XXX6",
    "country": "US",
    "industry": "Software",
    "registration_number": "ZEON1XXX23456",
    "director_id": "D-9981"
  },
  "person": {
    "name": "alice smith",
    "phone": "+1-800-555-1XXX2",
    "email": "[email protected]",
    "address": "456 Tech Valley, Silicon XXXXCity",
    "date_of_birth": "1990-06-12"
  }
}

Response Structure

All successful API responses include a result object:

Response Structure

{
  "api_version": "2.0.0",
  "entity": {
    "name": "alpha corp"
  },
  "result": {
    "found": true,
    "results": [
      {
        "opensanctions": {
          "birth_date": "1975-03-12",
          "country": "United States",
          "description": "Entity involved in financial misconduct and banned from serving as company director under SEC regulations.",
          "gender": "N/A",
          "name": "Alpha International Holdings Inc.",
          "relevance": "high",
          "source": "OpenSanctions",
          "source_link": "https://www.opensanctions.org/entities/alpha-international-holdings/",
          "source_name": "us_sec_banned_directors",
          "type": "sanctions_record"
        }
      },
      {
        "opensanctions": {
          "birth_date": "1968-09-22",
          "country": "Cayman Islands",
          "description": "Listed under OFAC SDN list due to suspected links to money laundering operations.",
          "gender": "N/A",
          "name": "Alpha International Holdings Inc.",
          "relevance": "medium",
          "source": "OpenSanctions",
          "source_link": "https://www.opensanctions.org/entities/alpha-international-holdings/",
          "source_name": "us_ofac_sdn",
          "type": "sanctions_record"
        }
      }
    ],
    "status": "completed",
    "summary": "Found in OpenSanctions (18 records)",
    "total_results": 2
  },
  "success": true
}

GET

GET /api/v2/check/{entity_id}

This endpoint retrieves the check result for a specific entity by its ID.

Request Example:

curl -X GET \ 'https://riskintelapi.cloudastra.co/api/v2/check/NK-xyz123ABcDE89012' \-H 'Authorization: Bearer your_token'

Request Payload:

None (entity ID in URL)

Response Example:

Response Structure

{
  "data": {
    "api_version": "2.0.0",
    "entity": {
      "name": "alpha corp"
    },
    "result": {
      "found": true,
      "results": [
        {
          "opensanctions": {
            "birth_date": "Not available",
            "country": "Not available",
            "description": "No description available",
            "gender": "Not available",
            "name": "ALPHXXXERNATIONXXXOLDINGXXXNC.",
            "relevance": "high",
            "source": "OpenSanctions",
            "source_link": "",
            "source_name": "us_sec_banned_directors",
            "type": "sanctions_record"
          }
        },
        {
          "opensanctions": {
            "birth_date": "Not available",
            "country": "Not available",
            "description": "No description available",
            "gender": "Not available",
            "name": "ALPHA XXXXGLOBXXXTECHNOLOGIXXXLLC",
            "relevance": "medium",
            "source": "OpenSanctions",
            "source_link": "",
            "source_name": "us_ofac_sdn",
            "type": "sanctions_record"
          }
        }
      ],
      "status": "completed",
      "summary": "Found in OpenSanctions (18 records)",
      "total_results": 2
    },
    "success": true
  }
}

Pagination

For list endpoints (e.g., logs, entities, sources), pagination is done via limit and offset parameters.

limit: Maximum number of records to return (e.g. limit=50)
offset: Number of records to skip (e.g. offset=100)

Example Response

Pagination

{
  "data": {
    "total": 1050,
    "offset": 0,
    "limit": 50,
    "count": 50,
    "items": [
      {
        "entity": "John Smith"
      },
      "..."
    ]
  }
}

Errors

OpenSancton API uses standard HTTP status codes:

Status	Type	Message
400	invalid-request	Request body is invalid JSON
401	unauthorized	Token is missing or expired
403	forbidden	Access denied
404	not-found	Resource not found
429	rate-limit-exceeded	Too many requests
500	server-error	Internal server error

Example:

Errors

{
  "error": {
    "type": "rate-limit-exceeded",
    "message": "You have exceeded the limit of 20 requests/sec."
  }
}

Rate Limiting

Global limit: 250,000 requests/minute (per user/IP)
Per-resource limit: 30 requests/second (e.g., per entity, per dataset)

If you exceed limits, a 429 error is returned.

Retry Strategy (Exponential Backoff)

DELAY = 500ms\nwhile request fails with 429:\n  wait random(DELAY, 2*DELAY)\nDELAY *= 2