Batch Screening

Screen multiple entities in a single request (up to 100).

Endpoint: POST /v1/screen/batch

---

Request

Headers

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

Request Body

Field	Type	Required	Description
entities	array	Yes	Array of entity objects (max 100)
options	object	No	Screening options for all entities

Entity Object

Field	Type	Required	Description
name	string	Yes	Entity name to screen
entity_type	string	No	Entity type classification
identifiers	object	No	Document numbers

Options Object

Field	Type	Default	Description
threshold	number	0.85	Confidence threshold
lists	array	["ofac_sdn"]	Lists to screen against
max_results_per_entity	number	5	Max matches per entity

---

Example Request

curl -X POST "https://api.sanctionswise.orchestraprime.ai/v1/screen/batch" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      {"name": "Vladimir Putin", "entity_type": "individual"},
      {"name": "Bank of Russia", "entity_type": "organization"},
      {"name": "Sergey Lavrov", "entity_type": "individual"},
      {"name": "John Smith", "entity_type": "individual"},
      {"name": "Acme Corporation", "entity_type": "organization"}
    ],
    "options": {
      "threshold": 0.60,
      "lists": ["ofac_sdn"],
      "max_results_per_entity": 3
    }
  }'

---

Response

{
  "batch_id": "BATCH-20251210183031-DEBF51ED",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "query": {"name": "Vladimir Putin", "entity_type": "individual"},
      "status": "potential_match",
      "match_count": 3,
      "matches": [
        {
          "entity_id": "sw_ofac_sdn_35096",
          "matched_name": "VLADIMIR VLADIMIROVICH PUTIN",
          "confidence_score": 0.762,
          "match_type": "fuzzy"
        }
      ]
    },
    {
      "index": 1,
      "query": {"name": "Bank of Russia", "entity_type": "organization"},
      "status": "potential_match",
      "match_count": 2,
      "matches": [...]
    },
    {
      "index": 2,
      "query": {"name": "Sergey Lavrov", "entity_type": "individual"},
      "status": "potential_match",
      "match_count": 1,
      "matches": [...]
    },
    {
      "index": 3,
      "query": {"name": "John Smith", "entity_type": "individual"},
      "status": "clear",
      "match_count": 0,
      "matches": []
    },
    {
      "index": 4,
      "query": {"name": "Acme Corporation", "entity_type": "organization"},
      "status": "clear",
      "match_count": 0,
      "matches": []
    }
  ],
  "summary": {
    "total": 5,
    "clear": 2,
    "matches": 0,
    "potential_matches": 3
  },
  "options_used": {
    "threshold": 0.60,
    "lists_screened": ["ofac_sdn"],
    "max_results_per_entity": 3
  },
  "timestamp": "2025-12-10T18:30:31.000000Z",
  "processing_time_ms": 49,
  "entities_per_second": 102.04
}

---

Response Fields

Field	Type	Description
batch_id	string	Unique identifier for this batch
status	string	completed or partial
results	array	Results for each entity
summary	object	Aggregate statistics
options_used	object	Options applied to all entities
timestamp	string	ISO 8601 timestamp
processing_time_ms	number	Total processing time
entities_per_second	number	Throughput metric

---

When to Use Batch Screening

Scenario	Recommended	Rationale
Less than 5 entities	Single requests	Lower latency per entity
5-100 entities	Batch request	Amortized setup cost
More than 100 entities	Multiple batch requests	API limit is 100 per batch
Real-time payment	Single request	Immediate response needed
Daily watchlist check	Batch request	Throughput over latency

---

Code Examples

Python - Process Large List

def screen_large_list(entities, batch_size=100):
    """Screen large entity lists efficiently."""
    results = []

    for i in range(0, len(entities), batch_size):
        batch = entities[i:i + batch_size]

        response = requests.post(
            f"{BASE_URL}/screen/batch",
            headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
            json={
                "entities": batch,
                "options": {"threshold": 0.85, "max_results_per_entity": 3}
            }
        )

        batch_results = response.json()
        results.extend(batch_results["results"])

        # Log progress
        print(f"Processed {min(i + batch_size, len(entities))}/{len(entities)}")

    return results

JavaScript - Async Batch Processing

async function screenBatch(entities, threshold = 0.85) {
  const response = await axios.post(
    `${BASE_URL}/screen/batch`,
    {
      entities,
      options: { threshold }
    },
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Usage
const entities = [
  { name: 'John Smith', entity_type: 'individual' },
  { name: 'Acme Corp', entity_type: 'organization' }
];
const result = await screenBatch(entities);
console.log(`Clear: ${result.summary.clear}, Flagged: ${result.summary.potential_matches}`);