@verisafe-aml/sdk

Official TypeScript / JavaScript SDK for the VeriSafe AML public REST API. Manage personas, operaciones, beneficial owners and ownership graphs from any Node.js (≥18) backend, plus a webhook signature verifier — for sujetos obligados under Spain's Ley 10/2010 + EU AMLR (Reg. UE 2024/1624).

Install

npm install @verisafe-aml/sdk

Requires Node 18+ (uses built-in fetch). Zero runtime dependencies.

Quick start

import { VeriSafeAML } from '@verisafe-aml/sdk';

const client = new VeriSafeAML({
  apiKey: process.env.VERISAFE_API_KEY!,
  // baseUrl: 'https://staging.verisafeaml.com/functions/v1', // optional override
});

// Create a person
const created = await client.people.create({
  external_id: 'crm-1234',
  type: 'individual',
  full_name: 'María García López',
  identification_type: 'dni',
  identification_number: '12345678Z',
  identification_country: 'ES',
  nationality: 'ES',
  country_of_residence: 'ES',
  // RTS Art. 28(1) AMLR multi-name + multi-nationality
  names: [
    { full_name: 'Mari G. López', name_type: 'alias', script: 'latin' },
  ],
});

// Add a non-primary document
await client.people.documents.create(created.data.id, {
  document_type: 'passport',
  document_number: 'AAA123456',
  issuing_country: 'ES',
  expiration_date: '2030-12-31',
});

// Ingest an operation
await client.operations.create({
  external_id: 'op-2026-04-001',
  operation_date: '2026-04-15',
  amount: 12500,
  currency: 'EUR',
  payment_method: 'transferencia',
  parties: [
    { person_external_id: 'crm-1234', role: 'ordenante' },
    { person_external_id: 'vendor-5678', role: 'beneficiario' },
  ],
});

API surface

The SDK mirrors the 5 public Edge Functions (7 user-facing resources):

| Resource | Methods | Notes | | --- | --- | --- | | client.people | list, get, create, update, ownershipTree | Soft-delete is in-app only | | client.people.documents | list, create, update, delete | DELETE supported on non-primary documents | | client.people.addresses | list, create, update, delete | Same | | client.people.smos | list, add, update, remove | Senior Managing Officials (Art. 46(5) AMLR fallback) | | client.people.beneficialOwners | list, add, update, remove | Declared UBO register | | client.operations | list, get, create, update | Idempotent on external_id AND reference_number | | client.entities.screenings | list | Read-only (generated by KYC sessions) | | client.entities.alerts | list | Read-only (monitoring engine emits) | | client.entities.cases | list | Read-only (case lifecycle) | | client.ownership | list, get, create, update, delete | Structural ownership graph | | client.tickets | list, create | Pensado para partners |

All list methods support pagination (page, page_size) and incremental sync (modified_since).

Authentication

The SDK uses the X-API-Key header. Create a key at Configuración → API → Claves in the VeriSafe AML dashboard. Keys are per-organization and can be revoked at any time. They never expire automatically.

Idempotency

Every POST that creates a resource accepts external_id (string, unique per organization + resource). Re-sending a request with the same external_id returns the existing record with duplicate: true rather than creating a new one. /api-operations additionally accepts reference_number as a second idempotency key.

Incremental sync

All list methods accept modified_since (ISO-8601 timestamp). The response only includes resources updated since that moment, ordered by updated_at ascending. Combine with pagination to build at-least-once pull pipelines.

let cursor = lastSyncedAt;
while (true) {
  const { data, meta } = await client.operations.list({
    modified_since: cursor,
    page_size: 100,
  });
  if (data.length === 0) break;
  for (const op of data) {
    await mySystem.upsertOperation(op);
    cursor = op.updated_at;
  }
  if (data.length < meta.page_size) break;
}

Webhook signature verification

VeriSafe AML signs every webhook delivery with HMAC-SHA256 over the raw request body, using the endpoint's signing secret. The signature is sent in the X-VeriSafe-Signature header as sha256=<hex>.

import express from 'express';
import { verifyWebhookSignature } from '@verisafe-aml/sdk';

const app = express();

// Capture raw body BEFORE JSON parsing (signature is over the raw bytes).
app.use(express.json({
  verify: (req, _res, buf) => {
    (req as any).rawBody = buf.toString('utf8');
  },
}));

app.post('/webhooks/verisafe', (req, res) => {
  const isValid = verifyWebhookSignature({
    body: (req as any).rawBody,
    signature: req.header('X-VeriSafe-Signature'),
    secret: process.env.VERISAFE_WEBHOOK_SECRET!,
  });

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const eventType = req.header('X-VeriSafe-Event');
  const payload = req.body;

  switch (eventType) {
    case 'person.created':   /* ... */ break;
    case 'person.updated':   /* ... */ break;
    case 'operation.created': /* ... */ break;
    case 'alert.created':    /* ... */ break;
    // ... 40+ events; see https://www.verisafeaml.com/api-docs#catalogo-de-eventos
  }

  res.status(200).send('ok');
});

Error handling

import { VeriSafeAMLApiError } from '@verisafe-aml/sdk';

try {
  await client.people.create({ /* ... */ });
} catch (err) {
  if (err instanceof VeriSafeAMLApiError) {
    if (err.code === 'INSUFFICIENT_CREDITS') {
      // Refill credits + retry
    } else if (err.status === 422) {
      // Validation error — err.body has details
    }
  }
  throw err;
}

The client retries automatically on 429 (respecting Retry-After) and on transient 5xx errors with exponential backoff. Default budget: 2 retries.

Rate limits

100 req/min and 5000 req/h per organization by default. Configurable by the org admin. When exceeded, the API responds 429 with Retry-After; the SDK retries automatically.

Development

npm install
npm run build
npm run typecheck

Links

• API docs: https://www.verisafeaml.com/api-docs
• Help center: https://www.verisafeaml.com/help
• Webhook event catalog: https://www.verisafeaml.com/help/api-webhooks/webhooks-salientes
• AMLR readiness: https://www.verisafeaml.com/compliance/amlr

License

MIT © ARWEN VENTURES SL (VeriSafe AML)