Skip to main content

Getting Started Guide

This guide walks you through everything you need to start screening entities against US Federal sanctions lists.

Prerequisites​

Before you begin, you'll need:

  • An AWS account (for AWS Marketplace subscription)
  • Basic familiarity with REST APIs
  • A programming language/HTTP client of your choice

Step 1: Subscribe to SanctionsWise API​

Via AWS Marketplace​

  1. Visit AWS Marketplace
  2. Search for "SanctionsWise"
  3. Select your pricing tier:
    • Free: 500 calls/month (ideal for evaluation)
    • Starter: 5,000 calls/month ($99/month)
    • Professional: 25,000 calls/month ($299/month)
    • Enterprise: Custom pricing
  4. Click "Subscribe"
  5. Complete the subscription process

Direct Access​

Contact sales@orchestraprime.ai for:

  • Volume discounts
  • Custom contracts
  • Enterprise features

Step 2: Get Your API Key​

After subscribing:

  1. Go to app.orchestraprime.ai
  2. Sign in with your AWS credentials
  3. Navigate to API Keys section
  4. Click Create API Key
  5. Copy and securely store your API key
Important

Keep your API key secure. Never commit it to source control or expose it in client-side code.

Step 3: Make Your First API Call​

Using cURL​

curl -X POST https://api.orchestraprime.ai/sanctionswise/screen/entity \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "entity_type": "individual"
  }'

Using Python​

import requests

response = requests.post(
    "https://api.orchestraprime.ai/sanctionswise/screen/entity",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "John Smith",
        "entity_type": "individual"
    }
)

result = response.json()
print(f"Status: {result['status']}")

Using JavaScript​

const response = await fetch(
  'https://api.orchestraprime.ai/sanctionswise/screen/entity',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Smith',
      entity_type: 'individual'
    })
  }
);

const result = await response.json();
console.log(`Status: ${result.status}`);

Step 4: Understand the Response​

A successful screening response looks like:

{
  "status": "clear",
  "matches": [],
  "audit_token": "at_abc123...",
  "data_freshness": {
    "ofac_sdn": "2025-12-11T08:00:00Z",
    "bis_entity": "2025-12-08T00:00:00Z"
  },
  "request_id": "req_xyz789"
}

Response Status Values​

StatusMeaningAction
clearNo matches foundSafe to proceed
matchHigh confidence matchReview required
potential_matchLower confidenceManual review recommended

Step 5: Handle Matches​

When matches are found:

{
  "status": "match",
  "matches": [
    {
      "entity_id": "sdn_12345",
      "name": "SMITH, John",
      "score": 0.95,
      "match_types": ["exact", "fuzzy"],
      "list_id": "ofac_sdn",
      "programs": ["SDGT"],
      "source": {
        "authority": "US Treasury OFAC",
        "list_name": "Specially Designated Nationals",
        "entry_id": "12345"
      }
    }
  ],
  "audit_token": "at_abc123..."
}
  1. Store the audit token for compliance records
  2. Review match details including score and match types
  3. Escalate to compliance team for final decision
  4. Document the decision with the audit token

Step 6: Set Up Production Integration​

Environment Variables​

# Set in your environment
export SANCTIONSWISE_API_KEY=your-api-key
export SANCTIONSWISE_BASE_URL=https://api.orchestraprime.ai/sanctionswise

Error Handling​

Always implement proper error handling:

import requests

def screen_entity(name, entity_type="individual"):
    try:
        response = requests.post(
            f"{BASE_URL}/screen/entity",
            headers={"x-api-key": API_KEY},
            json={"name": name, "entity_type": entity_type},
            timeout=30
        )
        response.raise_for_status()
        return response.json()

    except requests.exceptions.Timeout:
        # Handle timeout
        raise Exception("Request timed out")

    except requests.exceptions.HTTPError as e:
        if response.status_code == 429:
            # Handle rate limiting
            retry_after = response.headers.get("Retry-After", 60)
            raise Exception(f"Rate limited. Retry after {retry_after}s")
        elif response.status_code == 401:
            raise Exception("Invalid API key")
        else:
            raise Exception(f"API error: {e}")

Logging​

Log all screening requests for audit purposes:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("sanctionswise")

def screen_with_logging(name, entity_type):
    logger.info(f"Screening: {name} ({entity_type})")

    result = screen_entity(name, entity_type)

    logger.info(f"Result: {result['status']}, audit_token: {result['audit_token']}")

    return result

Next Steps​

Now that you're set up:

  1. Explore the API Reference - Learn about all available endpoints

  2. Understand Matching - Learn how our 5-layer matching works

  3. Review Best Practices - Optimize your integration

  4. Use SDKs - Simplify your integration

Getting Help​

SanctionsWise API is a product of OrchestraPrime LLC