Test environment
VerifyVAT provides a dedicated test environment to safely develop and validate your integration without affecting production data or consuming real API quotas.
The test environment is currently available for the /verify endpoint, which is the most complex and critical part of the integration. It includes a range of predefined test ID values that trigger specific responses, allowing you to simulate various scenarios.
You can access the test environment using the same API endpoints and SDKs as production, but with a test API key. See Authentication for details on obtaining and managing API keys.
curl "https://api.verifyvat.com/v1/verify" \ -H "x-api-key: {YOUR_TEST_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "type": "xx_test", "id": "XX2001" }'Simulate different scenarios
You can use the xx_test ID type with specific XX•••• ID values to simulate successful validations, different error conditions, and edge cases. See the table below for a catalog of available test cases. For more details on the response structure, the payload, and how to handle it in your integration, see Response envelope and Error handling.
Request-level errors XX0•••
Simulate request-level errors, such as ID type not found, missing required fields, and invalid parameter combinations. These cases return success=false with an appropriate error code and message.
| ID value | Scenario |
|---|---|
XX0000 | ID type not supported Returns an error for an ID type that is not currently supported. |
XX0001 | Not implemented Returns a not implemented error. |
XX0002 | Forbidden Returns a forbidden error. |
XX0003 | Bad request Returns a bad request error. |
Syntax failures XX1•••
Simulate inputs that fail syntax validation. No registries are contacted and entity is always null.
| ID value | Scenario |
|---|---|
XX1000 | Syntax invalid Input fails syntax validation, no registries are contacted, and entity is null. |
Registry outcomes XX2•••
Simulate normal registry outcomes such as no registry coverage, confirmed matches, unconfirmed matches, and partial coverage.
| ID value | Scenario |
|---|---|
XX2000 | No registry coverage The ID syntax is valid, but no registry coverage is available. The entity is null. |
XX2001 | Confirmed, single-source A confirmed outcome from the primary registry with a thin entity. |
XX2002 | Unconfirmed A registry has been contacted but the result is unconfirmed. The entity is null. |
XX2003 | Partial coverage A registry has been contacted but only partial coverage was available. The entity is null. |
XX2004 | Confirmed, multi-source A confirmed outcome with enrichment from a secondary source. |
Cache behaviour XX3•••
Simulate cache hits. Responses include a cache layer in process.sources and set process.output.origin to either fresh-cache or stale-cache.
| ID value | Scenario |
|---|---|
XX3000 | Fresh cache hit Confirmed result returned from fresh-cache. No registry contact needed. |
XX3001 | Stale cache hit Confirmed result returned from stale-cache. The registry was unreachable. |
Registry failures XX4•••
Simulate upstream registry problems that still return a successful envelope but produce an unknown verification outcome. This is useful to test resilience and fallback logic in clients.
| ID value | Scenario |
|---|---|
XX4000 | Registry unreachable The registry could not be reached, the outcome is unknown, and the entity is null. |
XX4001 | Integration error The registry was contacted but an error occurred on our side. The outcome is unknown and the entity is null. |
Entity shape traps XX5•••
Simulate confirmed results with tricky entity data. This group is meant to flush out assumptions in your projection, merge, and display logic. It includes multiple legal names, conflicting addresses, ended status, and sparse components.
| ID value | Scenario |
|---|---|
XX5000 | Conflicting names and addresses A confirmed outcome with conflicting values across sources for names and addresses. |
XX5001 | Ended status A confirmed outcome with an ended status record. |
XX5002 | Name history A confirmed outcome with name history (since/until) and timeline references. |
XX5003 | Geo nullable values A confirmed outcome where geolocation is present but contains null values. |
XX5004 | Baseline confirmed entity A confirmed outcome with a baseline entity graph. |
Authentication and billing XX9•••
Simulate common authentication errors such as missing API key, invalid API key, and rate limiting. These simulate the response envelope and headers you should expect in production.
| ID value | Scenario |
|---|---|
XX9000 | Missing API key Returns an authentication error indicating the API key is missing. |
XX9001 | Invalid API key Returns an authentication error indicating the API key is invalid or revoked. |
XX9002 | Daily limit exceeded Returns a rate limit error with daily limit headers. |
XX9003 | Burst limit exceeded Returns a rate limit error with burst limit headers. |
XX9004 | Monthly limit exceeded Returns a rate limit error with monthly limit headers. |
XX9005 | Billable overage request Returns a response indicating that the request exceeds the included quota and will be billed as overage. |
Unexpected crash XX9999
The single ID XX9999 value is reserved for a canonical unexpected server error response. Use it to validate your handling of unplanned error conditions, such as crashes or misconfigurations.