Changelog

Notable changes to the BizVerify API. For the machine-readable API schema, see the OpenAPI spec.

2026-06-16

Added

Agent-discovery metadata so the API is self-describing for AI agents and tooling. New read-only endpoints: an MCP Server Card at /.well-known/mcp/server-card.json, an A2A Agent Card at /.well-known/agent-card.json, an RFC 9727 API Catalog at /.well-known/api-catalog, and an Agent Skills index at /.well-known/agent-skills/index.json (with per-skill SKILL.md documents). The API root (GET /) now advertises these via RFC 8288 Link headers and serves a Markdown overview to clients that send Accept: text/markdown. These additions are purely discovery metadata — existing endpoints, request/response shapes, and authentication are unchanged, and SDKs need no update.

2026-06-15

Fixed

POST /v1/verify for Kentucky (us-ky) at the deep level could return the details of an unrelated business; it now consistently returns the correct entity. As part of this fix, the jurisdiction_id returned for Kentucky entities is now a stable, unique per-record identifier — so a Kentucky jurisdiction_id (and its corresponding cached entity_id) may differ from a value stored previously. quick verification and POST /v1/search were unaffected. No response shape or field changes; SDKs need no update.
POST /v1/verify for Florida (us-fl) at the deep level could fail with ENTITY_NOT_FOUND even when the business existed and matched; deep verification now reliably retrieves the full record for a matched Florida entity. No response shape or field changes.
Massachusetts (us-ma): when the current official record is temporarily unavailable, POST /v1/search and POST /v1/verify now return 503 DATA_SOURCE_UNAVAILABLE and are not charged, instead of returning an empty (but billed) result. Genuine no-match searches still return an empty result set as before.

2026-06-14

Changed

POST /v1/verify: when a jurisdiction’s data source can’t complete a synchronous lookup, the API now returns a precise status — 503 DATA_SOURCE_UNAVAILABLE or 504 DATA_SOURCE_TIMEOUT — or falls back to an asynchronous verification job, instead of a generic 500. Asynchronous job results (check_job_status) and the verification.failed webhook now carry a matching category in their error message, so a temporary-outage failure is distinguishable from a timeout. No request shape or field changes; existing success responses are unaffected.

2026-06-13

Changed

GET /v1/entity/:id now returns the full business record directly at the top level — including registered_agent (an object with its address), officers, principal_address, and filing_history_summary — instead of a nested wrapper, and adds last_verified_at plus a snapshots count (retrieve the snapshots themselves via GET /v1/entity/:id/history). This aligns the cached-entity response with the verification response shape. Breaking change for any client that read the previous nested structure. The official Node, Python, and Go SDKs are updated to match.
Renamed two response timestamp fields for clearer, consistent naming. GET /v1/entity/:id now returns last_verified_at (when the entity was last refreshed against the official record), and each snapshot from GET /v1/entity/:id/history now returns verified_at. This is a breaking change for any client that read the previous field names.

2026-06-12

Fixed

force_refresh on POST /v1/verify is now applied only to deep verifications, as documented. On quick verifications (including a deep request that falls back to quick where deep is unavailable) the flag is ignored, so a recent stored result may be returned. Quick verifications remain 1 credit.

2026-06-11

Changed

webhook_url on POST /v1/verify must now resolve to a publicly reachable address. URLs pointing to private or reserved networks are rejected with a 400 VALIDATION_ERROR, and the same check is applied again before each webhook delivery.
POST /v1/verify now handles the optional Idempotency-Key header safely under concurrency. A retry carrying the same key still replays the original response without charging again, but a second request sent while the first is still being processed now returns 409 IDEMPOTENCY_CONFLICT instead of being processed (and charged) twice — retry once the first request completes. The header is documented in the OpenAPI schema and limited to 128 characters; longer values are rejected with 400 VALIDATION_ERROR.

2026-06-03

Changed

MCP tool descriptions now state each tool’s credit cost, authentication requirements, and usage guidance — improves tool selection for AI agents.

2026-06-01

Added

Three new verified jurisdictions: Massachusetts (us-ma), Wisconsin (us-wi), and Alabama (us-al)

Removed

Colorado (us-co) and Wyoming (us-wy) are temporarily unavailable while we work to restore coverage. 19 active jurisdictions total.

2026-05-24

Added

Root discovery endpoint — GET / returns a JSON entry point linking to the docs, API reference, OpenAPI spec, MCP endpoint, and health check
GET /.well-known/security.txt (RFC 9116) for security researchers

2026-05-05

Changed

POST /v1/search now charges credits only for jurisdictions that completed successfully — failed jurisdictions are refunded and listed in the new jurisdictions_failed response field.

Fixed

Async verification jobs that fail now correctly deliver the verification.failed webhook (previously sent verification.completed with empty data) and auto-refund credits.
GET /v1/verify/status/:jobId now returns the same response shape as the sync POST /v1/verify endpoint and includes entityId on completed jobs.
POST /v1/verify and POST /v1/search reject invalid jurisdictions before charging credits — users with low balances see the validation error rather than INSUFFICIENT_CREDITS.

Security

OAuth tokens now require the appropriate scope on REST account and billing routes (previously enforced only for MCP):
- account:read — GET /v1/account, GET /v1/account/usage, GET /v1/account/data-export
- account:write — PATCH /v1/account, PUT /v1/account/password, DELETE /v1/account, POST /v1/account/keys, DELETE /v1/account/keys/:keyId
- billing — GET /v1/billing, POST /v1/billing/purchase
API key auth continues to grant all scopes.

2026-04-18

Added

California (us-ca), Nevada (us-nv), New York (us-ny), and Wyoming (us-wy) now verified — 18 active jurisdictions total

2026-04-06

Added

LLM tool definitions served at GET /tools/openai.json and GET /tools/anthropic.json — auto-generated from MCP schemas
bizverify-agents Python package — LangChain and CrewAI tool wrappers with built-in execution
n8n-nodes-bizverify — n8n community node with 9 operations
AI Agents guide — integration docs for all supported platforms

2026-04-02

Added

Documentation site launched at docs.bizverify.co
Node.js SDK (@bizverify/sdk) and Python SDK (bizverify) published

2026-03-28

Added

MCP server at POST /mcp — connect BizVerify to Claude, Cursor, VS Code, and other AI tools
OAuth 2.1 + PKCE authentication for MCP clients
Dynamic Client Registration (RFC 7591)

2026-03-20

Added

Agent-first API refactor — unified passwordless auth flow (/v1/auth/request-access, /v1/auth/verify-access)
Standardized error responses with code, message, details, suggestion
Credit headers (X-Credits-Remaining, X-Credits-Charged) on all authenticated responses
GDPR data export endpoint (GET /v1/account/data-export)

Changed

API docs moved from /docs to /reference

2026-03-10

Added

Prometheus metrics endpoint for monitoring
Audit log for admin actions
Automated alerting when a jurisdiction’s availability changes
Better Stack log shipping

2026-03-01

Added

Admin dashboard at /internal/dashboard/
User management (search, credit adjustment, disable/enable)
Job management (list, retry, refund)

2026-02-28

Added

Webhook callbacks — receive notifications when jobs complete, fail, or are refunded
Search pagination (limit/offset on POST /v1/search)
Account management — email update, password change, account deletion (GDPR)
Jurisdiction gating — non-active jurisdictions rejected before credit deduction

2026-02-15

Added

Email verification and password reset flows
OpenAPI 3.1 spec generation with Scalar interactive docs
CORS configuration
Auto-refund on job failure
CI/CD pipeline

2026-02-01

Added

Initial API launch with 14 verified jurisdictions
Credit-based billing with Stripe checkout
Verification coverage across 50 US states and 11 international jurisdictions
Sentry error monitoring