# Vatly API Documentation

> Developer-friendly VAT & GST validation API for 32 countries

## Documentation Pages

- [Home](https://docs.vatly.dev/): Overview, value proposition, and quick example
- [Quickstart](https://docs.vatly.dev/quickstart): 3-step getting started guide with curl, Node.js, and Python examples
- [Authentication](https://docs.vatly.dev/authentication): API key format, storage, and usage
- [Response Format](https://docs.vatly.dev/response-format): Envelope pattern (data/error + meta), field descriptions
- [Rate Limits](https://docs.vatly.dev/rate-limits): Tiers (Free 500/mo, Pro 10k/mo, Business 50k/mo), burst limits (20/60/120 per minute), headers, Retry-After, reset cycle
- [Caching](https://docs.vatly.dev/caching): 24-hour TTL, cache detection via meta.cached, stale fallback (meta.stale) when upstream is down, usage counting
- [Supported Countries](https://docs.vatly.dev/supported-countries): 32 country codes (EU + GB + XI + CH + LI + NO + AU), routing (VIES/HMRC/BFS/Bronnysund/ABR), input normalization, requester_vat_number for consultation numbers
- [Tiers & Billing](https://docs.vatly.dev/billing): Free/Pro/Business tiers, Stripe billing, subscription statuses, upgrade/downgrade behavior
- [Test Mode](https://docs.vatly.dev/test-mode): Test keys (vtly_test_ prefix), magic VAT numbers for predictable scenarios, no quota usage, no upstream calls
- [Batch Validation](https://docs.vatly.dev/batch-validation): POST /v1/validate/batch, validate up to 50 VAT numbers in one request, Pro and Business tiers only
- [Async Validation](https://docs.vatly.dev/async-validation): POST /v1/validate/async and POST /v1/validate/async/batch, submit validation requests and receive results via webhook, Pro and Business tiers only, up to 200 items (Pro) or 1,000 items (Business) per async batch
- [Webhooks](https://docs.vatly.dev/webhooks): Receive async validation results via HTTP webhooks, HMAC-SHA256 signature verification, event types (validation.completed, validation.failed, batch.completed, test), delivery history and replay

## Error Reference

- [Error Overview](https://docs.vatly.dev/errors/overview): All error codes at a glance
- [missing_parameter](https://docs.vatly.dev/errors/missing_parameter): 400 - vat_number query parameter not provided
- [invalid_vat_format](https://docs.vatly.dev/errors/invalid_vat_format): 422 - VAT number format unrecognized or unsupported country
- [unauthorized](https://docs.vatly.dev/errors/unauthorized): 401 - Invalid or missing API key
- [rate_limit_exceeded](https://docs.vatly.dev/errors/rate_limit_exceeded): 429 - Monthly quota exhausted
- [burst_limit_exceeded](https://docs.vatly.dev/errors/burst_limit_exceeded): 429 - Per-minute burst limit exceeded
- [upstream_unavailable](https://docs.vatly.dev/errors/upstream_unavailable): 503 - VIES, HMRC, BFS, Bronnysund, or ABR unreachable or returned an error
- [tier_insufficient](https://docs.vatly.dev/errors/tier_insufficient): 403 - Feature requires a higher tier (e.g. batch validation on Free)
- [validation_error](https://docs.vatly.dev/errors/validation_error): 422 - Request body validation failed (e.g. batch endpoint)
- [invalid_json](https://docs.vatly.dev/errors/invalid_json): 400 - Request body contains malformed JSON
- [webhook_not_configured](https://docs.vatly.dev/errors/webhook_not_configured): 400 - No webhook URL configured for async validation

## API Reference

- [GET /v1/validate](https://docs.vatly.dev/api-reference/validate): Validate a VAT number and retrieve company details
- [POST /v1/validate/batch](https://docs.vatly.dev/api-reference/batch-validate): Validate up to 50 VAT numbers in a single request
- [POST /v1/validate/async](https://docs.vatly.dev/api-reference/async-validate): Submit a single VAT number for async validation (returns 202, delivers result via webhook)
- [POST /v1/validate/async/batch](https://docs.vatly.dev/api-reference/async-batch-validate): Submit up to 200 (Pro) or 1,000 (Business) VAT numbers for async validation
- [PUT /v1/webhooks/config](https://docs.vatly.dev/api-reference/upsert-webhook-config): Create or update webhook configuration
- [GET /v1/webhooks/config](https://docs.vatly.dev/api-reference/get-webhook-config): Get current webhook configuration
- [DELETE /v1/webhooks/config](https://docs.vatly.dev/api-reference/delete-webhook-config): Remove webhook configuration
- [POST /v1/webhooks/test](https://docs.vatly.dev/api-reference/test-webhook): Send a test webhook event
- [GET /v1/webhooks/deliveries](https://docs.vatly.dev/api-reference/list-webhook-deliveries): List webhook deliveries with cursor-based pagination
- [GET /v1/webhooks/deliveries/{id}](https://docs.vatly.dev/api-reference/get-webhook-delivery): Get full webhook delivery details
- [POST /v1/webhooks/deliveries/{id}/replay](https://docs.vatly.dev/api-reference/replay-webhook-delivery): Replay a webhook delivery

## Node.js SDK

- Package: `@vatly/node` (npm)
- Install: `npm install @vatly/node`
- Import: `import Vatly from '@vatly/node'` (default import)
- Key features: TypeScript-first, `{ data, error }` pattern (never throws), typed error classes (RateLimitError, UpstreamError, AuthenticationError), camelCase API, batch validation with `isBatchSuccess()` type guard
- Methods: `vatly.vat.validate()`, `vatly.vat.validateBatch()`, `vatly.rates.list()`, `vatly.rates.get()`

## Python SDK

- Package: `vatly` (PyPI)
- Install: `pip install vatly`
- Import: `from vatly import Vatly`
- Key features: sync and async support, typed exceptions (AuthenticationError, ValidationError, RateLimitError, UpstreamError), snake_case API
- Methods: `vatly.vat.validate()`, `vatly.vat.validate_batch()`, `vatly.rates.list()`, `vatly.rates.get()`