Screen Single Entity

Screen an individual or organization against sanctions lists.

Endpoint: POST /v1/screen/entity

---

Request

Headers

Header	Required	Description
x-api-key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

Field	Type	Required	Description
name	string	Yes	Entity name to screen (2-500 chars)
entity_type	string	No	individual, organization, vessel, aircraft, unknown
threshold	number	No	Confidence threshold 0.50-1.00 (default: 0.85)
lists	array	No	List IDs to screen against (default: ["ofac_sdn"])
identifiers	object	No	Document numbers for enhanced matching
countries	array	No	Associated countries for context
max_results	number	No	Maximum matches to return (default: 10, max: 50)

Identifiers Object

Field	Type	Description
passport	string	Passport number
national_id	string	National ID / SSN
tax_id	string	Tax ID / TIN / EIN
date_of_birth	string	Date of birth (YYYY-MM-DD)
registration	string	Company registration number

---

Example Request

curl -X POST "https://api.sanctionswise.orchestraprime.ai/v1/screen/entity" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vladimir Putin",
    "entity_type": "individual",
    "threshold": 0.60,
    "lists": ["ofac_sdn"],
    "identifiers": {
      "passport": "AB1234567"
    }
  }'

---

Response

Match Found

{
  "screening_id": "SCR-20251210185252-2FFDC8AE",
  "status": "potential_match",
  "query": {
    "name": "Vladimir Putin",
    "entity_type": "individual",
    "threshold": 0.60,
    "lists_screened": ["ofac_sdn"]
  },
  "matches": [
    {
      "entity_id": "sw_ofac_sdn_35096",
      "matched_name": "VLADIMIR VLADIMIROVICH PUTIN",
      "confidence_score": 0.7714,
      "match_type": "fuzzy",
      "entity_details": {
        "primary_name": "VLADIMIR VLADIMIROVICH PUTIN",
        "entity_type": "individual",
        "nationality": "Russia",
        "programs": ["RUSSIA-EO14024", "UKRAINE-EO13660"],
        "listing_date": "2022-02-25"
      },
      "source_evidence": {
        "source_authority": "US Treasury OFAC",
        "source_list_id": "ofac_sdn",
        "source_entry_uid": "sw_ofac_sdn_35096",
        "last_updated": "2025-12-10T17:26:38Z"
      }
    }
  ],
  "match_count": 10,
  "timestamp": "2025-12-10T18:52:52.527387Z",
  "processing_time_ms": 378,
  "data_freshness": {
    "last_update": "2025-12-10T17:26:38Z"
  }
}

No Match (Clear)

{
  "screening_id": "SCR-20251210190000-12345678",
  "status": "clear",
  "query": {
    "name": "John Smith",
    "entity_type": "individual",
    "threshold": 0.85,
    "lists_screened": ["ofac_sdn"]
  },
  "matches": [],
  "match_count": 0,
  "timestamp": "2025-12-10T19:00:00.000000Z",
  "processing_time_ms": 45,
  "data_freshness": {
    "last_update": "2025-12-10T17:26:38Z"
  }
}

---

Response Fields

Field	Type	Description
screening_id	string	Unique identifier for this screening
status	string	clear, match, or potential_match
query	object	The original query parameters
matches	array	List of matching entities
match_count	number	Total matches found
timestamp	string	ISO 8601 timestamp
processing_time_ms	number	Processing time in milliseconds
data_freshness	object	Data update timestamps

---

Status Values

Status	Description	Action Required
clear	No matches above threshold	None - proceed with transaction
match	High-confidence match (≥95%)	Block transaction, escalate
potential_match	Matches found requiring review	Manual review required

---

Error Responses

400 Bad Request

{
  "error": "Field \"name\" is required and must be a string"
}

401 Unauthorized

{
  "message": "Unauthorized"
}

---

Code Examples

Python

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.sanctionswise.orchestraprime.ai/v1"

def screen_entity(name, entity_type="individual", threshold=0.85):
    response = requests.post(
        f"{BASE_URL}/screen/entity",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "name": name,
            "entity_type": entity_type,
            "threshold": threshold
        }
    )
    return response.json()

# Example usage
result = screen_entity("Vladimir Putin", threshold=0.60)
print(f"Status: {result['status']}, Matches: {result['match_count']}")

JavaScript

const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.sanctionswise.orchestraprime.ai/v1';

async function screenEntity(name, entityType = 'individual', threshold = 0.85) {
  const response = await axios.post(
    `${BASE_URL}/screen/entity`,
    {
      name,
      entity_type: entityType,
      threshold
    },
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Example usage
screenEntity('Vladimir Putin', 'individual', 0.60)
  .then(result => {
    console.log(`Status: ${result.status}, Matches: ${result.match_count}`);
  });