@vigilhq/sdk

Official TypeScript/JavaScript SDK for the Vigil compliance screening API.

Installation

npm install @vigilhq/sdk
# or
pnpm add @vigilhq/sdk
# or
yarn add @vigilhq/sdk

Quick Start

import { Vigil } from "@vigilhq/sdk";

const client = new Vigil({ apiKey: "vgl_sk_live_..." });

// Screen an entity
const result = await client.screen({ entity: "John Doe" });
console.log(result.status);          // "clear"
console.log(result.risk_score);      // 12
console.log(result.recommendation);  // "approve"

// Screen with context to reduce false positives
const result2 = await client.screen({
  entity: "Jane Smith",
  context: "onboarding",
  date_of_birth: "1990-01-15",
  nationality: "CA",
});

// Check a sanctioned entity
const result3 = await client.screen({ entity: "Osama bin Laden" });
console.log(result3.status);          // "match"
console.log(result3.risk_level);      // "critical"
console.log(result3.recommendation);  // "block"

API Reference

new Vigil(config)

| Option | Type | Default | Description | |-----------|----------|--------------------------|----------------------| | apiKey | string | — | Your Vigil API key | | baseUrl | string | https://api.vigilhq.dev | API base URL | | timeout | number | 30000 | Request timeout (ms) |

Screening

// Screen an entity
const result = await client.screen({ entity: "John Doe", context: "onboarding" });

// Get a past screening result
const past = await client.getScreening("scr_abc123");

// List screenings (paginated)
const list = await client.listScreenings({ page: 1, per_page: 25 });

Batch Screening

// Submit batch (up to 1,000 entities)
const job = await client.batchScreen([
  { entity: "Entity A" },
  { entity: "Entity B" },
]);

// Wait for completion
const completed = await client.waitForBatch(job.job_id);

Continuous Monitoring

// Add entity to monitoring
await client.addMonitoredEntity({ entity: "Acme Corp", entity_type: "organization" });

// List monitored entities
const monitored = await client.listMonitoredEntities();

// Remove from monitoring
await client.removeMonitoredEntity("mon_abc123");

API Keys

const newKey = await client.createApiKey({ name: "production" });
const keys = await client.listApiKeys();
await client.revokeApiKey("key_abc123");

Webhooks

await client.createWebhook({ url: "https://example.com/webhook", events: ["screening.completed"] });
const webhooks = await client.listWebhooks();
await client.deleteWebhook("wh_abc123");

Organization & Usage

const org = await client.getOrg();
const usage = await client.getUsage("2026-02");

Error Handling

import { Vigil, VigilError } from "@vigilhq/sdk";

try {
  await client.screen({ entity: "test" });
} catch (err) {
  if (err instanceof VigilError) {
    console.log(err.code);    // "RATE_LIMIT_EXCEEDED"
    console.log(err.status);  // 429
    console.log(err.message); // "Monthly screening limit reached..."
  }
}

License

MIT