verisafe-aml 0.1.0

Official Python SDK for the VeriSafe AML public REST API. Manage personas, operaciones, beneficial owners and ownership graphs, plus a webhook signature verifier — for sujetos obligados under Spain's Ley 10/2010 + EU AMLR.

verisafe-aml (Python SDK)

Official Python SDK for the VeriSafe AML public REST API. Companion to the Node SDK (@verisafe-aml/sdk).

Status

0.1.0 — alpha. Core surface (people + operations) is shipped; nested resources (documents, addresses, beneficial owners, ownership graph, tickets, entities) land in 0.2.0+. The Node SDK has the full surface — use it if you need everything today.

Install

pip install verisafe-aml

Requires Python ≥3.9.

Quick start

import os
from verisafe_aml import VeriSafeAML

client = VeriSafeAML(api_key=os.environ["VERISAFE_API_KEY"])

# Create a person
created = 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",
)

# Ingest an operation
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"},
    ],
)

# Incremental sync
last = "2026-05-01T00:00:00Z"
while True:
    page = client.operations.list(modified_since=last, page_size=100)
    if not page["data"]:
        break
    for op in page["data"]:
        my_system.upsert_operation(op)
        last = op["updated_at"]

Webhook signature verification

from fastapi import FastAPI, Request, HTTPException
from verisafe_aml import verify_webhook_signature
import os

app = FastAPI()
SECRET = os.environ["VERISAFE_WEBHOOK_SECRET"]

@app.post("/webhooks/verisafe")
async def webhook(request: Request):
    body = await request.body()  # raw bytes — do NOT use await request.json()
    signature = request.headers.get("X-VeriSafe-Signature")
    if not verify_webhook_signature(body, signature, SECRET):
        raise HTTPException(401, "Invalid signature")
    event = request.headers.get("X-VeriSafe-Event")
    payload = await request.json()
    # dispatch on event ...
    return {"ok": True}

Idempotency, rate limits, errors

Same semantics as the Node SDK — see the API docs for details. The client retries automatically on 429 (respecting Retry-After) and on transient 5xx with exponential backoff.

from verisafe_aml import VeriSafeAMLApiError

try:
    client.people.create(...)
except VeriSafeAMLApiError as e:
    if e.code == "INSUFFICIENT_CREDITS":
        # ...
        pass
    raise

Development

pip install -e '.[dev]'
pytest

Roadmap

• 0.2.0: nested document/address/SMO/BO resources
• 0.3.0: ownership graph + tickets + entities (read-only screenings/alerts/cases)
• 0.4.0: typed Pydantic models for all responses
• 1.0.0: async variant via httpx.AsyncClient

Links

• API docs: https://www.verisafeaml.com/api-docs
• Help center: https://www.verisafeaml.com/help
• Node SDK (full surface): https://github.com/verisafe-aml/verisafe-aml-sdk-node

License

MIT © ARWEN VENTURES SL (VeriSafe AML)