{"openapi":"3.0.3","info":{"title":"BizVerify API","description":"Business entity verification API. Verify company registrations, search business entities, and check good standing across US states and international jurisdictions. Authenticate with an API key via the X-API-Key header.","version":"1.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API key authentication. Obtain a key via POST /v1/auth/request-access and POST /v1/auth/verify-access."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth","description":"OAuth 2.1 Bearer token. Obtain via the /oauth/authorize flow."}},"schemas":{}},"paths":{"/health":{"get":{"operationId":"healthCheck","tags":["Meta"],"description":"Health check endpoint. Returns 200 if the API, database, and Redis are all operational. Returns 503 if any component is degraded. No authentication required.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded"],"description":"Overall system status"},"checks":{"type":"object","additionalProperties":{"type":"string"},"description":"Individual component checks (database, redis) with status \"ok\" or \"error\""},"timestamp":{"type":"string","description":"ISO 8601 timestamp of the health check"}},"required":["status","checks","timestamp"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded"],"description":"Overall system status"},"checks":{"type":"object","additionalProperties":{"type":"string"},"description":"Individual component checks (database, redis) with status \"ok\" or \"error\""},"timestamp":{"type":"string","description":"ISO 8601 timestamp of the health check"}},"required":["status","checks","timestamp"],"additionalProperties":false}}}}}}},"/v1/jurisdictions":{"get":{"operationId":"listJurisdictions","tags":["Meta"],"description":"List all registered jurisdictions and their verification capabilities (quick, deep, search, entity lookup). No authentication required. For active jurisdictions only, use GET /v1/config.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"jurisdictions":{"type":"array","items":{}}},"required":["jurisdictions"],"additionalProperties":false}}}}}}},"/tools/openai.json":{"get":{"operationId":"getOpenAiToolDefinitions","summary":"OpenAI function calling tool definitions","tags":["Tools"],"description":"Returns BizVerify tool definitions in OpenAI function calling format. Use these to register BizVerify tools with any OpenAI-compatible model.","responses":{"200":{"description":"Default Response"}}}},"/tools/anthropic.json":{"get":{"operationId":"getAnthropicToolDefinitions","summary":"Anthropic tool use definitions","tags":["Tools"],"description":"Returns BizVerify tool definitions in Anthropic tool use format. Use these to register BizVerify tools with any Anthropic-compatible model.","responses":{"200":{"description":"Default Response"}}}},"/v1/config":{"get":{"operationId":"getConfig","tags":["Public"],"description":"Get public configuration including supported jurisdictions, credit pricing, available features, and API status. No authentication required. Use this to discover supported jurisdictions and understand credit costs before making API calls.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"jurisdictions":{"type":"object","properties":{"stats":{"type":"object","properties":{"totalJurisdictions":{"type":"number"},"usStates":{"type":"number"},"countries":{"type":"number"}},"required":["totalJurisdictions","usStates","countries"],"additionalProperties":false},"supported":{"type":"object","properties":{"us":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"capabilities":{"type":"object","properties":{"search":{"type":"boolean"},"entityLookup":{"type":"boolean"},"supportsQuick":{"type":"boolean"},"supportsDeep":{"type":"boolean"},"availableFields":{"type":"array","items":{"type":"string"}}},"required":["search","entityLookup","supportsQuick","supportsDeep","availableFields"],"additionalProperties":false}},"required":["name","code","capabilities"],"additionalProperties":false}},"international":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"capabilities":{"type":"object","properties":{"search":{"type":"boolean"},"entityLookup":{"type":"boolean"},"supportsQuick":{"type":"boolean"},"supportsDeep":{"type":"boolean"},"availableFields":{"type":"array","items":{"type":"string"}}},"required":["search","entityLookup","supportsQuick","supportsDeep","availableFields"],"additionalProperties":false}},"required":["name","code","capabilities"],"additionalProperties":false}},"comingSoon":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"}},"required":["name","code"],"additionalProperties":false}}},"required":["us","international","comingSoon"],"additionalProperties":false}},"required":["stats","supported"],"additionalProperties":false},"checker":{"type":"object","properties":{"jurisdictions":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"code":{"type":"string"}},"required":["label","code"],"additionalProperties":false}}},"required":["jurisdictions"],"additionalProperties":false},"pricing":{"type":"object","properties":{"creditCosts":{"type":"object","properties":{"quick":{"type":"number"},"deep":{"type":"number"},"deepForceRefresh":{"type":"number"},"search":{"type":"number"},"entityHistory":{"type":"number"},"entityLookup":{"type":"number"}},"required":["quick","deep","deepForceRefresh","search","entityHistory","entityLookup"],"additionalProperties":false},"freeTier":{"type":"object","properties":{"credits":{"type":"number"},"replenish":{"type":"string"},"rateLimit":{"type":"string"}},"required":["credits","replenish","rateLimit"],"additionalProperties":false},"packages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"credits":{"type":"number"},"price":{"type":"string"},"pricePerCredit":{"type":"string"},"highlighted":{"type":"boolean"},"badge":{"type":"string"}},"required":["name","credits","price","pricePerCredit","highlighted"],"additionalProperties":false}}},"required":["creditCosts","freeTier","packages"],"additionalProperties":false},"features":{"type":"object","properties":{"webhooks":{"type":"boolean"},"pagination":{"type":"boolean"},"asyncJobs":{"type":"boolean"}},"required":["webhooks","pagination","asyncJobs"],"additionalProperties":false},"rateLimits":{"type":"object","properties":{"default":{"type":"number"}},"required":["default"],"additionalProperties":false},"status":{"type":"object","properties":{"api":{"type":"string"},"lastUpdated":{"type":"string"}},"required":["api","lastUpdated"],"additionalProperties":false},"legal":{"type":"object","properties":{"terms_url":{"type":"string"},"privacy_url":{"type":"string"},"acceptable_use_url":{"type":"string"},"version":{"type":"string"}},"required":["terms_url","privacy_url","acceptable_use_url","version"],"additionalProperties":false},"docs":{"type":"object","properties":{"openapi":{"type":"string"},"interactive":{"type":"string"}},"required":["openapi","interactive"],"additionalProperties":false}},"required":["jurisdictions","checker","pricing","features","rateLimits","status","legal","docs"],"additionalProperties":false}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Public"],"description":"Download the OpenAPI 3.1 specification as JSON. Use this to generate client SDKs or explore the API schema programmatically.","responses":{"200":{"description":"Default Response"}}}},"/v1/auth/request-access":{"post":{"operationId":"requestAccess","tags":["Auth"],"description":"Request API access — creates an account if needed and sends a verification code to the provided email. Use with POST /v1/auth/verify-access to complete the flow and receive an API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email address to register or re-authenticate"},"accept_terms":{"type":"boolean","description":"Must be true to accept terms of service"}},"required":["email","accept_terms"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable status message"}},"required":["message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/verify-access":{"post":{"operationId":"verifyAccess","tags":["Auth"],"description":"Verify the email code from POST /v1/auth/request-access and receive a new API key. The email is marked as verified upon success.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email address used in request-access"},"code":{"type":"string","minLength":6,"maxLength":6,"description":"6-digit verification code sent to the email"},"label":{"description":"Optional label for the new API key","type":"string","minLength":1,"maxLength":100}},"required":["email","code"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"API key for authenticating requests. Store securely — it will not be shown again."},"key_id":{"type":"string","description":"Unique identifier for the API key"},"label":{"type":"string","description":"Label assigned to the API key"}},"required":["api_key","key_id","label"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/verify":{"post":{"operationId":"verifyBusiness","tags":["Verification"],"description":"Verify a business entity by name in a specific jurisdiction. Returns verification results synchronously if available within timeout, or a job ID for async retrieval via GET /v1/verify/status/:jobId. Charges credits based on tier: quick (1 credit), deep (15 credits), deep + force_refresh (25 credits). The response includes `full_verification_available` indicating whether deep verification is supported for the jurisdiction. When deep is not available, a `reason` object is returned. When webhook_url is provided, the result is delivered as a POST request to that URL once the async job completes, fails, or is refunded.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_name":{"type":"string","minLength":1,"maxLength":500,"description":"The business name to verify, e.g. \"Acme Corporation\""},"jurisdiction":{"type":"string","minLength":2,"maxLength":10,"description":"Jurisdiction code, e.g. \"us-fl\" for Florida or \"gb\" for Great Britain"},"entity_type":{"description":"Optional entity type filter to narrow results","type":"string","enum":["llc","corporation","lp","llp","sole_proprietorship","nonprofit","general_partnership","other"]},"verification_level":{"default":"quick","description":"Verification tier: \"quick\" (1 credit) returns existence + status. \"deep\" (15 credits) returns full entity details including officers, registered agent, formation date, and filing history. Deep is only available in a subset of jurisdictions; requesting deep where unavailable returns a quick result with a reason.","type":"string","enum":["quick","deep"]},"force_refresh":{"default":false,"description":"If true, returns the most current result instead of a previously stored one. Applies to deep verification only (cost: 25 credits instead of 15); ignored on quick verifications.","type":"boolean"},"webhook_url":{"description":"Optional URL to receive webhook notifications when the async job completes, fails, or is refunded. Must be a publicly reachable http(s) URL.","type":"string","format":"uri"}},"required":["entity_name","jurisdiction"]}}}},"parameters":[{"schema":{"type":"string","maxLength":128},"in":"header","name":"idempotency-key","required":false,"description":"Optional key to make this request idempotent. Retries carrying the same key replay the original response instead of charging again; a concurrent retry while the first is still processing returns 409 IDEMPOTENCY_CONFLICT. Max 128 characters."}],"security":[{"apiKey":[]}],"callbacks":{"verificationResult":{"{$request.body#/webhook_url}":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","job_id","jurisdiction","entity_name","status","credits_charged","credits_refunded","completed_at"],"properties":{"event":{"type":"string","enum":["verification.completed","verification.failed","verification.refunded"],"description":"The webhook event type"},"job_id":{"type":"string","description":"The verification job ID"},"jurisdiction":{"type":"string","description":"Jurisdiction code (e.g. us-fl, gb)"},"entity_name":{"type":"string","description":"The entity name that was verified"},"status":{"type":"string","enum":["completed","failed","refunded"],"description":"The job outcome status"},"data":{"type":"object","nullable":true,"description":"Verification result data (present on completed)"},"error":{"type":"string","nullable":true,"description":"Error message (present on failed)"},"credits_charged":{"type":"integer","description":"Number of credits charged for this job"},"credits_refunded":{"type":"boolean","description":"Whether credits were refunded"},"completed_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of completion"}}}}}},"responses":{"2XX":{"description":"Webhook accepted"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Job status: \"completed\" (sync result) or \"pending\" (async — poll via GET /v1/verify/status/:jobId)"},"verification_level":{"type":"string","enum":["quick","deep"],"description":"The tier at which verification was performed. May differ from the requested level if deep was requested but not available for this jurisdiction."},"full_verification_available":{"type":"boolean","description":"Whether deep verification is available for this jurisdiction"},"reason":{"description":"Present when full_verification_available is false, explaining the tier result","type":"object","properties":{"code":{"type":"string","enum":["jurisdiction_quick_only"],"description":"Reason code for tier availability"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["code","message"],"additionalProperties":false},"data":{"description":"Verification result data, present when status is \"completed\""},"job_id":{"description":"Job ID for async polling, present when status is \"pending\"","type":"string"},"entity_id":{"description":"Cached entity ID, present when a match was found","type":"string"},"cached":{"type":"boolean","description":"Whether the result was served from cache"},"credits_charged":{"type":"number","description":"Number of credits deducted for this request"}},"required":["status","verification_level","full_verification_available","cached","credits_charged"],"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Job status: \"completed\" (sync result) or \"pending\" (async — poll via GET /v1/verify/status/:jobId)"},"verification_level":{"type":"string","enum":["quick","deep"],"description":"The tier at which verification was performed. May differ from the requested level if deep was requested but not available for this jurisdiction."},"full_verification_available":{"type":"boolean","description":"Whether deep verification is available for this jurisdiction"},"reason":{"description":"Present when full_verification_available is false, explaining the tier result","type":"object","properties":{"code":{"type":"string","enum":["jurisdiction_quick_only"],"description":"Reason code for tier availability"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["code","message"],"additionalProperties":false},"data":{"description":"Verification result data, present when status is \"completed\""},"job_id":{"description":"Job ID for async polling, present when status is \"pending\"","type":"string"},"entity_id":{"description":"Cached entity ID, present when a match was found","type":"string"},"cached":{"type":"boolean","description":"Whether the result was served from cache"},"credits_charged":{"type":"number","description":"Number of credits deducted for this request"}},"required":["status","verification_level","full_verification_available","cached","credits_charged"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/verify/status/{jobId}":{"get":{"operationId":"getVerificationStatus","tags":["Verification"],"description":"Check the status of an async verification job. Poll this endpoint after POST /v1/verify returns status \"pending\" with a job_id. Returns the full verification result once the job completes.","parameters":[{"schema":{"type":"string"},"in":"path","name":"jobId","required":true,"description":"The job ID returned from POST /v1/verify"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/entity/{entityId}":{"get":{"operationId":"getEntity","tags":["Entities"],"description":"Get a cached entity by ID. Returns the most recent verification data for the entity. Entity IDs are returned by POST /v1/verify and POST /v1/search. No credits charged.","parameters":[{"schema":{"type":"string"},"in":"path","name":"entityId","required":true,"description":"The entity ID returned from a verification or search"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The cached entity ID"},"jurisdiction":{"type":"string","description":"Jurisdiction code, e.g. \"us-fl\" or \"gb\""},"jurisdiction_id":{"nullable":true,"description":"The entity identifier within its jurisdiction","type":"string"},"entity_name":{"type":"string","description":"The registered business name"},"entity_type":{"type":"string","enum":["llc","corporation","lp","llp","sole_proprietorship","nonprofit","general_partnership","other"],"description":"The entity type"},"status":{"type":"string","enum":["active","inactive","dissolved","suspended","revoked","merged","withdrawn","unknown"],"description":"The registration status"},"good_standing":{"nullable":true,"description":"Whether the entity is in good standing (null if not determinable)","type":"boolean"},"formation_date":{"nullable":true,"description":"Formation/registration date, if available","type":"string"},"registered_agent":{"nullable":true,"description":"The registered agent, if available","type":"object","properties":{"name":{"type":"string"},"address":{"nullable":true,"type":"object","properties":{"line1":{"type":"string"},"line2":{"nullable":true,"type":"string"},"city":{"type":"string"},"state":{"nullable":true,"type":"string"},"postal_code":{"nullable":true,"type":"string"},"country":{"type":"string"}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false}},"required":["name","address"],"additionalProperties":false},"officers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"address":{"nullable":true,"type":"object","properties":{"line1":{"type":"string"},"line2":{"nullable":true,"type":"string"},"city":{"type":"string"},"state":{"nullable":true,"type":"string"},"postal_code":{"nullable":true,"type":"string"},"country":{"type":"string"}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false}},"required":["name","title","address"],"additionalProperties":false},"description":"Known officers/directors"},"principal_address":{"nullable":true,"description":"Principal office address, if available","type":"object","properties":{"line1":{"type":"string"},"line2":{"nullable":true,"type":"string"},"city":{"type":"string"},"state":{"nullable":true,"type":"string"},"postal_code":{"nullable":true,"type":"string"},"country":{"type":"string"}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false},"filing_history_summary":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"type":{"type":"string"},"description":{"nullable":true,"type":"string"}},"required":["date","type","description"],"additionalProperties":false},"description":"Recent filing history"},"last_verified_at":{"nullable":true,"description":"ISO 8601 timestamp of the most recent verification, if any","type":"string"},"snapshots":{"type":"number","description":"Number of verification snapshots on record for this entity"},"created_at":{"type":"string","description":"ISO 8601 timestamp of when the entity was first cached"},"updated_at":{"type":"string","description":"ISO 8601 timestamp of the most recent update"}},"required":["id","jurisdiction","jurisdiction_id","entity_name","entity_type","status","good_standing","formation_date","registered_agent","officers","principal_address","filing_history_summary","last_verified_at","snapshots","created_at","updated_at"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/entity/{entityId}/history":{"get":{"operationId":"getEntityHistory","tags":["Entities"],"description":"Get historical verification snapshots for an entity, ordered by most recent first. Each snapshot represents a point-in-time verification result. Charges 5 credits per request. Supports pagination via limit and offset query parameters.","parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"entityId","required":true,"description":"The entity ID returned from a verification or search"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"snapshots":{"type":"array","items":{}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["snapshots","total","limit","offset"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search":{"post":{"operationId":"searchEntities","tags":["Search"],"description":"Search for business entities across one or multiple jurisdictions. Returns matching entities with confidence scores. Charges 2 credits per jurisdiction searched. Use the jurisdiction parameter to search a specific jurisdiction, or omit it to search all active jurisdictions. Supports pagination via limit and offset. Search is available in every active jurisdiction regardless of verification tier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_name":{"type":"string","minLength":1,"maxLength":500,"description":"The business name to search for, e.g. \"Acme\""},"jurisdiction":{"description":"Optional jurisdiction code to search. Omit to search all active jurisdictions.","type":"string","minLength":2,"maxLength":10},"entity_type":{"description":"Optional entity type filter to narrow results","type":"string","enum":["llc","corporation","lp","llp","sole_proprietorship","nonprofit","general_partnership","other"]},"limit":{"default":50,"description":"Maximum number of results to return (default 50, max 200)","type":"integer","minimum":1,"maximum":200},"offset":{"default":0,"description":"Number of results to skip for pagination","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entity_name"]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{},"description":"Array of matching business entities with confidence scores"},"total":{"type":"number","description":"Total number of matching results across all searched jurisdictions"},"limit":{"type":"number","description":"The limit that was applied"},"offset":{"type":"number","description":"The offset that was applied"},"jurisdictions_searched":{"type":"array","items":{"type":"string"},"description":"List of jurisdiction codes that were searched"},"jurisdictions_failed":{"type":"array","items":{"type":"string"},"description":"Subset of jurisdictions_searched that could not be completed (credits refunded for these)"},"credits_charged":{"type":"number","description":"Net credits deducted after partial refunds for failed jurisdictions"}},"required":["results","total","limit","offset","jurisdictions_searched","jurisdictions_failed","credits_charged"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/":{"get":{"operationId":"getAccount","tags":["Account"],"description":"Get your account details including email, plan, credit balance, and all API keys. Use this to check your current credit balance before making API calls.","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Your account ID"},"email":{"type":"string","description":"Account email address"},"email_verified":{"type":"boolean","description":"Whether the email has been verified"},"plan":{"type":"string","enum":["free","paid"],"description":"Current billing plan"},"credit_balance":{"type":"number","description":"Current credit balance available for API calls"},"api_keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique API key identifier"},"label":{"type":"string","description":"Human-readable label for the key"},"prefix":{"type":"string","description":"First 8 characters of the key for identification"},"rate_limit":{"type":"number","description":"Requests per minute allowed for this key"},"is_active":{"type":"boolean","description":"Whether the key is currently active"},"created_at":{"description":"When the key was created","type":"string","format":"date-time"}},"required":["id","label","prefix","rate_limit","is_active","created_at"],"additionalProperties":false},"description":"All API keys associated with this account"},"created_at":{"description":"When the account was created","type":"string","format":"date-time"}},"required":["id","email","email_verified","plan","credit_balance","api_keys","created_at"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"operationId":"updateEmail","tags":["Account"],"description":"Update your account email address. Sets email_verified to false and sends a verification email to the new address. You must re-verify before using credit-consuming endpoints.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"New email address. A verification email will be sent to this address."}},"required":["email"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Your account ID"},"email":{"type":"string","description":"Account email address"},"email_verified":{"type":"boolean","description":"Whether the email has been verified"},"plan":{"type":"string","enum":["free","paid"],"description":"Current billing plan"},"credit_balance":{"type":"number","description":"Current credit balance available for API calls"},"api_keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique API key identifier"},"label":{"type":"string","description":"Human-readable label for the key"},"prefix":{"type":"string","description":"First 8 characters of the key for identification"},"rate_limit":{"type":"number","description":"Requests per minute allowed for this key"},"is_active":{"type":"boolean","description":"Whether the key is currently active"},"created_at":{"description":"When the key was created","type":"string","format":"date-time"}},"required":["id","label","prefix","rate_limit","is_active","created_at"],"additionalProperties":false},"description":"All API keys associated with this account"},"created_at":{"description":"When the account was created","type":"string","format":"date-time"}},"required":["id","email","email_verified","plan","credit_balance","api_keys","created_at"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/usage":{"get":{"operationId":"getUsageStats","tags":["Account"],"description":"Get API usage statistics for your account, broken down by day, endpoint, and jurisdiction. Useful for monitoring consumption and identifying usage patterns.","parameters":[{"schema":{"default":30,"type":"integer","minimum":1,"maximum":90},"in":"query","name":"days","required":false,"description":"Number of days to look back (default 30, max 90)"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/data-export":{"get":{"operationId":"getDataExport","tags":["Account"],"description":"Export all your account data including profile, API keys, credit transactions, verification jobs, and usage statistics (GDPR right to data portability).","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/keys":{"post":{"operationId":"createApiKey","tags":["Account"],"description":"Create a new API key with a descriptive label. The full key is returned only once — store it securely. You can create multiple keys for different environments or integrations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100,"description":"A descriptive label for the API key, e.g. \"Production\" or \"CI/CD\""}},"required":["label"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique key identifier"},"key":{"type":"string","description":"The full API key. Store securely — it will not be shown again."},"prefix":{"type":"string","description":"First 8 characters of the key for identification"},"label":{"type":"string","description":"The label you provided"},"message":{"type":"string","description":"Reminder to store the key securely"}},"required":["id","key","prefix","label","message"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/keys/{keyId}":{"delete":{"operationId":"revokeApiKey","tags":["Account"],"description":"Revoke an API key immediately. The key will no longer authenticate requests. This action is irreversible.","parameters":[{"schema":{"type":"string"},"in":"path","name":"keyId","required":true,"description":"The API key ID to revoke"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"204":{"description":"Key revoked"},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/billing/":{"get":{"operationId":"getBilling","tags":["Billing"],"description":"Get your current credit balance, available credit packages for purchase, and recent transaction history. Supports pagination for transaction history via limit and offset query parameters.","parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false,"description":"Maximum number of transactions to return (default 50, max 200)"},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false,"description":"Number of transactions to skip for pagination"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number","description":"Current credit balance"},"packages":{"description":"Available credit packages for purchase"},"transactions":{"description":"Recent credit transactions (purchases, deductions, refunds)"}},"required":["balance","packages","transactions"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/billing/purchase":{"post":{"operationId":"purchaseCredits","tags":["Billing"],"description":"Create a Stripe checkout session to purchase a credit package. Returns a Stripe URL to redirect the user to for payment. Credits are added to your balance automatically after successful payment via webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"package_id":{"type":"string","enum":["credits_100","credits_500","credits_2000","credits_10000"],"description":"Credit package ID to purchase. See GET /v1/billing for available packages."}},"required":["package_id"]}}}},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","description":"Stripe checkout session ID"},"url":{"type":"string","description":"Stripe checkout URL — redirect the user here to complete payment"}},"required":["session_id","url"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"suggestion":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}}}