UK sanctions API in Node.js: FCDO coverage and customer checks

{
  "subject": {
    "name": "Mira Calder",
    "entityType": "person",
    "birthDate": "1984"
  },
  "package": "sandbox@1",
  "retention": "standard"
}

// Node.js 22+. Run on your trusted backend; no npm dependencies.
import { readFileSync } from 'node:fs';
const base = 'https://www.sanctionskit.com/api/v1';
async function main() {
  const key = process.env.SANCTIONSKIT_API_KEY;
  const operation = process.env.SCREENING_OPERATION_ID;
  if (!key || !operation) throw new Error('Set your key and operation ID.');
  const request = JSON.parse(readFileSync(process.argv[2] ?? 'request.json', 'utf8'));
  const sandbox = request.package === 'sandbox@1';
  const sourceIds = sandbox ? ['sandbox-synthetic'] : request.sources;
  if (!Array.isArray(sourceIds) || !sourceIds.length) throw new Error('Select your sources.');
  async function api(path, body) {
    const response = await fetch(base + path, {
      method: body ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(25000),
      headers: { Authorization: 'Bearer ' + key,
        ...(body ? { 'Content-Type': 'application/json', 'Idempotency-Key': operation } : {}) },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
    const envelope = await response.json();
    if (!response.ok) {
      const code = /^[a-z0-9_]{1,80}$/.test(envelope?.error?.code ?? '') ? envelope.error.code : 'unknown';
      throw new Error('API HTTP ' + response.status + ': ' + code);
    }
    return envelope?.data;
  }
  if (!sandbox) {
    const sources = await api('/sources');
    if (!Array.isArray(sources)) throw new Error('Invalid discovery response.');
    for (const id of sourceIds) {
      const found = sources.filter(source => source?.id === id);
      const source = found[0];
      if (found.length !== 1 || source.availability !== 'available' || source.fresh !== true ||
          !Array.isArray(source.capabilities) || !source.capabilities.includes(request.subject.entityType)) throw new Error('Required source unavailable or incompatible.');
    }
  }
  const result = await api('/screenings', request);
  if (typeof result?.id !== 'string' || !result.id || result.environment !== (sandbox ? 'sandbox' : 'production') ||
      !['potential_match', 'no_match'].includes(result.status) ||
      !Array.isArray(result.matches) || (result.status === 'no_match') !== (result.matches.length === 0) ||
      !Array.isArray(result.coverage) || result.coverage.length !== sourceIds.length ||
      sourceIds.some(id => result.coverage.filter(item => item.sourceId === id && item.fresh === true).length !== 1)) {
    throw new Error('Incomplete screening result.');
  }
  // Store result.id with your customer reference; use results:read to retrieve the evidence.
  console.log(JSON.stringify({ id: result.id, status: result.status,
    candidateCount: result.matches.length, sources: result.coverage.map(item => item.sourceId) }));
}
await main().catch(error => {
  console.error((/^API HTTP [0-9]{3}: [a-z0-9_]{1,80}$/.test(error.message) ||
    error.message === 'Required source unavailable or incompatible.')
    ? error.message : 'Screening incomplete. Check credentials, request and source coverage.');
  process.exitCode = 1;
});

node screen.mjs request.json

curl --fail-with-body --max-time 25 --header "Authorization: Bearer $SANCTIONSKIT_API_KEY" "https://www.sanctionskit.com/api/v1/sources"

{
  "subject": {
    "name": "Mira Calder",
    "entityType": "person",
    "birthDate": "1984"
  },
  "sources": [
    "uk-sanctions"
  ],
  "retention": "standard"
}