Changelog

Verifa uses date-based API versioning. Breaking changes are released as new dated versions. Non-breaking changes (new fields, new endpoints, new webhook events) ship continuously and are available on all versions.

See Versioning for how to pin your API version.

2026-08-31 — Proof-of-address retry context in the SDK config

  • GET /api/v1/sdk/config proof_of_address.accepted_type_options rows now carry the full document-type record — category, default_max_age_days, review_only, and counts_as_independent alongside key and label — so clients can render policy-aware pickers without vendoring the type table.
  • New proof_of_address.retry_reasons: the reason codes from the most recent failed or review-routed proof-of-address check ({code, severity}), for showing the user what to fix before re-uploading.
  • A rejected proof-of-address upload no longer appears in resume_state.uploaded_doc_types, so a resumed session re-opens the upload step instead of skipping past it.

2026-08-27 — Proof of address policy

proof_of_address_check is now policy-driven and country-aware. It resolves an explicit proof-of-address policy — accepted document types, per-type and per-country recency windows, PO-box and business-address rules, and separate pass/review thresholds for name and address — instead of a single fixed threshold. See Proof of address.

Three-state check result

  • details.outcome is one of passed, review, or failed. A review outcome surfaces as passed: false plus details.action_override: "review" and routes the session to your review queue rather than rejecting it. Integrations that read only passed keep their existing behaviour.
  • details.reasons is a list of {code, severity, message} findings. Codes are stable; severity is fail, review, or info.
  • details.policy snapshots the effective policy the check ran under, so a decision stays explainable after the settings change.
  • New fields on details: document_type_detected, issuing_country, issuer, address_type, period_start / period_end, holder_names, forensics, and a component-level cross_reference breakdown (name_score, address_score, component_scores, partial, partial_reasons).
  • issuer, holder_names, and extracted_address are personal data — they are never exposed through the MCP server.

New rejection reason code

  • poa_review joins the existing poa_failed on rejection_reason_code.

New upload field

  • poa_issuing_country — ISO 3166-1 alpha-2 code of the country that issued the proof-of-address document. Accepted on POST /api/v1/sessions/{session_id}/documents and on the capture-token POST /verify/{token}/additional-document. Optional; defaults to the session’s ID-document country.
  • poa_document_type now documents the full canonical enum (15 subtypes). It stays optional but is strongly recommended — without it the check cannot apply the per-type recency window. The legacy values rental_agreement and vehicle_registration are still accepted and normalised to lease_agreement and government_letter.

New endpoints

  • GET /api/v1/settings/proof-of-address — the organization’s stored policy, the resolved effective policy, the regional presets, the canonical document type table, and the country list.
  • PUT /api/v1/settings/proof-of-address — replace the stored policy. Requires the manage_settings permission; writes a settings.proof_of_address.update audit entry. Dashboard cookie only — not callable with an API key.

SDK config

  • GET /api/v1/sdk/config — the proof_of_address block now returns accepted_types as a list of canonical subtype keys (strings) already filtered by the effective policy, with the matching display labels in accepted_type_options ({key, label} objects), plus require_issuing_country and default_issuing_country.

Dashboard

  • New Settings → Proof of address page: preset picker, editable document type × window matrix, country overrides, policy toggles, and threshold sliders.
  • The proof_of_address_check workflow node can either use the organization settings or override them for a single workflow.

2026-05-21 — MCP server

Verifa now speaks the Model Context Protocol at https://api.withverifa.com/mcp. AI agents (Claude Code, Cursor, Claude Desktop, the Anthropic API MCP connector) can call 45 structured tools against your account without LLM-generated cURL. See the MCP Server integration guide for the full surface.

New endpoints

  • POST /mcp — Streamable HTTP MCP transport. Bearer-authenticated by existing API keys. Supports ?toolsets=… filter and ?read_only=true flag at connect time.
  • GET /.well-known/oauth-protected-resource — RFC 9728 protected resource metadata. Currently advertises Bearer-only (empty authorization_servers list); future OAuth support will populate it.

New audit-log query

  • GET /api/v1/events?action_prefix=mcp — action_prefix is a new query param on the events endpoint; matches action LIKE 'prefix.%' so callers can scope to one source. Pair with mcp to surface only MCP tool calls. Both the model layer and dashboard “MCP only” filter use it.

New scope

  • redact:write — required for the five destructive MCP tools (redact session / identity / bulk / blocklist-entry / link-revoke) and the matching REST GDPR Art. 17 endpoints. Never granted by default, never available on publishable keys; manage on a per-key basis in the dashboard’s Developers → API Keys page.

New rate-limit bucket

  • MCP requests get a 120 requests / minute per API key bucket separate from the REST quota — a runaway agent on one key cannot starve the REST budget your integration depends on. Destructive MCP operations are throttled by a second bucket on top: 5 ops / hour per key.

Dashboard

  • New Integrations → AI / MCP page (URL builder + per-client config snippets).
  • Audit log gains an MCP only filter button.
  • API-key edit modal: new Destructive scope group with danger styling + a warning callout when enabled.

2026-04-17 — Pre-launch hardening release

New endpoints

  • DELETE /api/v1/screening-subjects/{subject_id}/data — GDPR Art. 17 erasure for a screening subject
  • DELETE /api/v1/me/account — Permanent erasure of the authenticated dashboard user’s account (Art. 17)
  • GET /api/v1/sessions/{session_id}/export — GDPR Art. 15 data subject access export
  • GET /api/v1/identities/{identity_id}/export — Same, aggregated across every session linked to an identity
  • POST /api/v1/auth/refresh — Refresh the dashboard session cookie

Webhook changes

  • Signature format: outbound webhooks now use Stripe-style X-Verifa-Signature: t=<unix_ts>,v1=<hex_hmac>. Update your verifier per the new tutorial. Legacy bare-hex format remains accepted during a deprecation window so in-flight deliveries continue to verify.
  • Per-endpoint signing secret is now the source of truth (the whsec_* returned at endpoint creation/rotation). The legacy org-level webhook secret is the fallback only.
  • New event: consortium.match_found — fired when face matching detects the same identity across orgs in the Verifa Network.
  • identity.flagged payload: removed flagged_by and flag_reason (privacy hardening); added has_reason: bool.

Behavior changes

  • Cross-environment isolation: live API keys can no longer read sandbox sessions/identities/workflows and vice versa. Requests with mismatched env return 404. If you were using a live key against sandbox IDs by mistake, you’ll start seeing 404s.
  • X-Request-Id header is echoed on every API response. Pass X-Request-Id on inbound requests to correlate logs end-to-end.
  • Vendor name scrubbing: verification_check.details.providers now uses sanitized labels (e.g. "aml_screening") instead of raw vendor names like "complyadvantage". The session verifications API never returns vendor names directly anymore.
  • Field length limits: request bodies for sessions, cases, identities, screening enforce maxLength on string fields, maxItems on lists, and a 16 KB cap on metadata dicts. Oversized inputs return 422 Validation Error.

Operational

  • AML enhanced add-on now requires an annual billing plan with a minimum $5,000 annual contract value (per ComplyAdvantage commercial terms). Existing active addons are grandfathered.
  • SAML IdP-initiated sign-in is opt-in per organization (default off). Contact support to enable for orgs using Okta/Azure tile launch.
  • Free-plan-expired orgs now blocked at the API layer with a clear 403. Previously only the IDV quota path enforced this.

Internal hardening (not customer-visible)

  • Webhook delivery: per-endpoint atomic claim eliminates duplicate dispatches; retry storm capped to 5 attempts.
  • Vendor circuit breakers around ComplyAdvantage, MicroBilt, IPQS, TeleSign, Smarty, KYC service.
  • Sentry: PII scrubber attached to before_send so emails/SSN/phone/card numbers/JWT/API keys never reach Sentry events.
  • JSON-formatted logs (LOG_FORMAT=json) for structured log shipping.
  • New /health/full deep-dependency probe (gated by X-Metrics-Token header).

2026-01-01 (current)

Initial public API version.

  • Session lifecycle: create, retrieve, list, expire, redact
  • Document OCR extraction
  • Face match with configurable security levels
  • Workflow engine with DAG-based execution
  • Webhook delivery with HMAC-SHA256 signatures
  • Key inflection support (kebab-case, camelCase, snake_case)
  • Idempotency for POST requests
  • Sandbox environment with simulated results
  • Basic watchlist screening (OFAC, EU, UN, UK sanctions)
  • Enhanced AML screening with continuous monitoring
  • Risk assessment with 150+ fraud signals
  • Duplicate detection across sessions
  • Standalone checks API (POST /api/v1/checks, POST /api/v1/checks/full)
  • Email risk enhanced and phone risk enhanced checks
  • Address validation check
  • Custom lists API (allow/block/flag lists)
  • PDF report generation for screening checks
  • GDPR redaction endpoint for checks
  • Identity cross-reference check (identity_crossref)
  • Proof of address check (proof_of_address_check)
  • Case templates and custom fields APIs
  • SCIM 2.0 provisioning
  • API log retrieval and analytics endpoints
  • Cursor-based pagination for identity listing
  • Rate limit headers on all responses

Non-breaking changes

These changes ship continuously and are available without a version upgrade.

April 2026

Standalone Documents & AI Extraction

New top-level Documents area in the dashboard. Upload documents, classify them automatically, extract structured fields, and run verification checks. Custom document types with extraction hints. Server-side PDF preview rendering. All extraction runs on Verifa’s private infrastructure — document data is never sent to third-party services.

  • Dashboard Documents page (list, detail, and upload)
  • Automatic classification against system and custom document types
  • Structured field extraction with per-field confidence scores
  • Recency checks via document groups
  • PDF page preview with page navigation
  • GET /documents now supports standalone=true and excludes redacted documents by default
  • New GET /documents/{id}/preview endpoint for server-side page rendering
  • Example “Health Insurance Card” document type seeded for new organizations

March 2026

  • NFC chip authentication check (nfc_chip_auth)
  • Mobile SDK endpoints (/api/v1/sdk/config, /api/v1/sdk/nfc, /api/v1/sdk/attest)
  • Device attestation for iOS and Android
  • Video-based liveness detection
  • Deepfake detection signal
  • Mobile-specific fraud signals (root/jailbreak, emulator, screen recording)
  • TOTP two-factor authentication for dashboard users

February 2026

  • Case escalation workflows with SLA tracking
  • Second-reviewer support for cases
  • Org-level feature overrides
  • Data retention policies with configurable periods
  • Webhook retry improvements (exponential backoff, 7 retries)

January 2026

  • Initial release
  • Dashboard with HTMX-based UI
  • Admin portal for platform management
  • RBAC with 6 admin roles and 5 org roles
  • Sandbox mode with all features unlocked

Upcoming

We publish planned changes here before they ship.

  • Client libraries — Official Python, TypeScript, Go, and Java SDKs (auto-generated from the OpenAPI spec)
  • GraphQL-style field selection — Request only the fields you need with a fields query parameter
  • Versioning — How to set and manage your API version
  • Webhooks — Subscribe to API change notifications
  • Errors — Error codes including version-related responses