# VATFind REST API
Reviewed: 2026-10-06. This reference is generated from the deployed OpenAPI contract.

Base URL: https://vatfind.com/v1
OpenAPI: https://vatfind.com/openapi.json
Human reference: https://vatfind.com/docs
Agent quickstart: https://vatfind.com/agents

## Authentication and first request
Create a sandbox key in https://vatfind.com/dashboard/api. Send Authorization: Bearer <VATFIND_API_KEY>. Use vf_test_ keys for deterministic fixtures with no credits; vf_live_ keys select live processing. Keys belong in server-side environment variables, never URLs or prompts.

First call GET /v1/countries/GB to inspect capabilities. Then POST /v1/companies/search with a name and country_code, plus a stable Idempotency-Key. Compare candidate identifiers before selecting an entity. Each billable live search or check consumes a workspace check; inspect current plan terms before running a batch.

```json
{"name":"Example Company","country_code":"GB"}
```

Sandbox companies are fixtures, not evidence about a real company. For a live request, use a real legal name and registration country. Public web allowances do not provide free live MCP or REST checks.

## Endpoints
| Method | Path | Purpose |
| --- | --- | --- |
| GET | /v1/ | Discover the VATFind API |
| HEAD | /v1/ | Read API discovery headers |
| OPTIONS | /v1/ | Read API discovery methods |
| POST | /v1/checks | Create a check |
| GET | /v1/checks | List checks |
| GET | /v1/checks/{check_id} | Get a check |
| POST | /v1/companies/search | Search company records |
| GET | /v1/companies/{company_id} | Get a company snapshot |
| GET | /v1/countries | List country capabilities |
| GET | /v1/countries/{country_code} | Get country capabilities |
| POST | /v1/monitors | Create a company-record monitor |
| GET | /v1/monitors | List company-record monitors |
| GET | /v1/monitors/{monitor_id} | Get a company-record monitor |
| PATCH | /v1/monitors/{monitor_id} | Update a company-record monitor |
| DELETE | /v1/monitors/{monitor_id} | Archive a company-record monitor |
| POST | /v1/monitors/{monitor_id}/run | Run a company-record monitor now |
| GET | /v1/monitoring-events | List company-monitoring events |
| GET | /v1/monitoring-events/{event_id} | Get a company-monitoring event |
| GET | /v1/usage | Get current-period usage |

## Errors and retries
401 means missing, invalid or revoked credentials. 403 means insufficient scope. 402 means paid access is required for a billable live operation. Handle 429 using Retry-After and the retryable flag. Preserve unavailable source states; do not turn them into invalid tax registrations. Retry the same billable operation with the original Idempotency-Key and identical body within 24 hours. A different body with the same key returns 409.

## Current commercial and coverage information
- Pricing: https://vatfind.com/pricing
- Country capabilities: https://vatfind.com/coverage
- Data and result boundaries: https://vatfind.com/data
- Service and licensing terms: https://vatfind.com/terms
- Security: https://vatfind.com/security
- Enterprise and bulk requirements: https://vatfind.com/contact

Field availability varies by country and source. A retrieval timestamp is not the registry's last-update timestamp. Keep format, company-record association, company legal status and tax-authority status separate. A missing field is not a negative check. Current REST checks do not call a live tax-authority service.