Skip to main content

JavaScript SDK

The official JavaScript/Node.js SDK for SanctionsWise API.

Installation​

npm install @orchestraprime/sanctionswise

Or with Yarn:

yarn add @orchestraprime/sanctionswise

Requirements:

  • Node.js 18 or higher
  • TypeScript 4.7+ (optional, for type support)

Quick Start​

import { SanctionsWiseClient } from '@orchestraprime/sanctionswise';

// Initialize client
const client = new SanctionsWiseClient({ apiKey: 'your-api-key' });

// Screen an entity
const result = await client.screenEntity({
  name: 'John Smith',
  entityType: 'individual'
});

console.log(`Status: ${result.status}`);
console.log(`Matches: ${result.matches.length}`);

Configuration​

API Key​

// Option 1: Pass directly
const client = new SanctionsWiseClient({ apiKey: 'your-api-key' });

// Option 2: Environment variable
// SANCTIONSWISE_API_KEY=your-api-key
const client = new SanctionsWiseClient();

// Option 3: Configuration object
const client = new SanctionsWiseClient({
  apiKey: process.env.SANCTIONSWISE_API_KEY
});

Options​

const client = new SanctionsWiseClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.orchestraprime.ai/sanctionswise', // Default
  timeout: 30000,      // Request timeout in ms
  maxRetries: 3,       // Retry attempts
  retryDelay: 1000,    // Initial retry delay in ms
});

Screening Methods​

Single Entity​

const result = await client.screenEntity({
  name: 'John Smith',
  entityType: 'individual',  // individual, organization, vessel
  lists: ['all'],            // or ['ofac_sdn', 'bis_entity']
  threshold: 0.85,           // Minimum match score
  includeSemantic: true      // Enable AI matching (Pro+)
});

// Access results
console.log(result.status);      // clear, match, potential_match
console.log(result.matches);     // Array of matches
console.log(result.auditToken);  // For compliance records

Batch Screening​

const entities = [
  { name: 'Entity One', entityType: 'individual' },
  { name: 'Entity Two', entityType: 'organization' },
  { name: 'Entity Three', entityType: 'individual' },
];

const results = await client.screenBatch({
  entities,
  lists: ['all'],
  threshold: 0.85
});

results.forEach(result => {
  console.log(`${result.name}: ${result.status}`);
});

Large List Processing​

async function processLargeList(entities, batchSize = 100) {
  const allResults = [];

  for (let i = 0; i < entities.length; i += batchSize) {
    const batch = entities.slice(i, i + batchSize);
    const results = await client.screenBatch({ entities: batch });
    allResults.push(...results);

    // Respect rate limits
    await sleep(100);
  }

  return allResults;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Entity Lookup​

// Get entity details by ID
const entity = await client.getEntity('sdn_12345');

console.log(entity.name);
console.log(entity.aliases);
console.log(entity.identifiers);
console.log(entity.addresses);
console.log(entity.programs);

List Operations​

// Get all available lists
const lists = await client.getLists();

lists.forEach(list => {
  console.log(`${list.listId}: ${list.entityCount} entities`);
});

// Get specific list details
const sdn = await client.getList('ofac_sdn');
console.log(`Last updated: ${sdn.lastUpdated}`);

TypeScript Support​

The SDK includes complete TypeScript definitions:

import {
  SanctionsWiseClient,
  ScreeningRequest,
  ScreeningResult,
  EntityType,
  ListId,
  Match
} from '@orchestraprime/sanctionswise';

async function screenCustomer(name: string): Promise<ScreeningResult> {
  const client = new SanctionsWiseClient();

  return client.screenEntity({
    name,
    entityType: EntityType.Individual
  });
}

Type Definitions​

interface ScreeningResult {
  status: 'clear' | 'match' | 'potential_match';
  matches: Match[];
  auditToken: string;
  dataFreshness: Record<string, string>;
  requestId: string;
}

interface Match {
  entityId: string;
  name: string;
  score: number;
  matchTypes: ('exact' | 'fuzzy' | 'phonetic' | 'semantic')[];
  listId: string;
  programs: string[];
  source: SourceInfo;
}

Error Handling​

import {
  SanctionsWiseError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  ServerError
} from '@orchestraprime/sanctionswise';

try {
  const result = await client.screenEntity({ name: 'Test' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.log('Check your API key');
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
    console.log(`Retry after ${error.retryAfter} seconds`);
    await sleep(error.retryAfter * 1000);
    // Retry request
  } else if (error instanceof ValidationError) {
    // Invalid request parameters
    console.log(`Validation error: ${error.message}`);
    console.log(`Field: ${error.field}`);
  } else if (error instanceof ServerError) {
    // Server-side error
    console.log('Service temporarily unavailable');
  } else if (error instanceof SanctionsWiseError) {
    // Any other API error
    console.log(`Error: ${error.message}`);
  }
}

Express.js Integration​

import express from 'express';
import { SanctionsWiseClient } from '@orchestraprime/sanctionswise';

const app = express();
const client = new SanctionsWiseClient();

app.use(express.json());

app.post('/api/screen', async (req, res) => {
  try {
    const { name, entityType } = req.body;

    const result = await client.screenEntity({
      name,
      entityType: entityType || 'individual'
    });

    res.json({
      status: result.status,
      matchCount: result.matches.length,
      auditToken: result.auditToken
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Browser Usage​

For browser environments, use the UMD build:

<script src="https://unpkg.com/@orchestraprime/sanctionswise/dist/browser.min.js"></script>
<script>
  const client = new SanctionsWise.Client({ apiKey: 'your-api-key' });

  client.screenEntity({ name: 'John Smith' })
    .then(result => console.log(result.status));
</script>
warning

Never expose your API key in client-side code. Use a backend proxy for production applications.

Complete Example​

/**
 * Complete sanctions screening workflow
 */

import { SanctionsWiseClient, RateLimitError } from '@orchestraprime/sanctionswise';

async function screenCustomers(customers) {
  const client = new SanctionsWiseClient();
  const results = { clear: [], matches: [], errors: [] };

  for (const customer of customers) {
    try {
      const result = await client.screenEntity({
        name: customer.name,
        entityType: customer.type || 'individual',
        threshold: 0.85
      });

      if (result.status === 'clear') {
        results.clear.push({
          customer,
          auditToken: result.auditToken
        });
      } else {
        results.matches.push({
          customer,
          matches: result.matches,
          auditToken: result.auditToken
        });
      }
    } catch (error) {
      if (error instanceof RateLimitError) {
        await sleep(error.retryAfter * 1000);
        // Retry logic here
      } else {
        results.errors.push({
          customer,
          error: error.message
        });
      }
    }
  }

  return results;
}

// Usage
const customers = [
  { name: 'John Smith', type: 'individual' },
  { name: 'Acme Corp', type: 'organization' },
];

screenCustomers(customers).then(results => {
  console.log(`Clear: ${results.clear.length}`);
  console.log(`Matches: ${results.matches.length}`);
});

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Resources​

SanctionsWise API is a product of OrchestraPrime LLC