> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Changelog

> API version history and recent changes.

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](/api-details/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](/core-concepts/verifications-checks#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](https://modelcontextprotocol.io)
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](/integration-guides/mcp-server) 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

## Related

* [Versioning](/api-details/versioning) — How to set and manage your API version
* [Webhooks](/api-details/webhooks) — Subscribe to API change notifications
* [Errors](/api-details/errors) — Error codes including version-related responses