What is it?
Sandbox environment in Lookup allows you to test your integration with the TIN Validation API without triggering real tax authority lookups. It simulates a wide range of outcomes, including successful validations, input issues, service errors, and delays — all through the same API endpoints used in production.
This ensures your implementation handles all realistic scenarios before you go live.
Key benefits
- Safe environment for QA and testing.
- Supports both common and edge-case responses.
- Same API structure and format as in production.
- Allows simulation of country-specific logic and error conditions.
- Features like webhooks or fuzzy matching work as in production
Supported test inputs for TIN validation
To simulate different validation outcomes, use the following TIN values. The behavior may vary depending on the country selected, even for the same TIN.
| TIN | Simulated Behavior |
|---|---|
1000 | Valid format, not found online |
2000 | Valid format, found online |
2100 | The same result as 2000, with 5–15s background processing delay |
2101 | The same result as 2000, with 1–3s ingestion delay (to simulate SLA breach) |
3000 | Special case for country-specific scenarios: • India – Simulates a PAN validation response • South Korea – Returns a tax-exempt case • Poland – Includes a deregistration_date field to test deregistered entities• Brazil – Returns individual-related fields for CPF validation |
5001 | Valid format, returns error_code: NETWORK_ERROR |
5002 | Valid format, returns error_code: TEMPORARY_UNAVAILABLE |
5003 | Valid format, returns error_code: UNKNOWN_RESPONSE |
5004 | Valid format, returns error_code: INCOMPLETE_IMPLEMENTATION |
5005 | Valid format, returns error_code: ONLINE_CHECK_NOT_SUPPORTED |
5006 | Valid format, returns error_code: TAX_AUTHORITY_CREDENTIALS_REJECTED |
5101 | Mexico only – returns error_code: MX_NAME_MISMATCH |
5102 | Mexico only – returns error_code: MX_ZIPCODE_MISMATCH |
5103 | Mexico only – returns error_code: MX_NAME_AND_ZIPCODE_MISMATCH |
5104 | USA only – returns error_code: TAX_AUTHORITY_SAME_TAX_ID_LIMIT_REACHED |
123456789 | USA only - an individual tin to demonstrate how SSN's are masked |
6000 | Returns error_code: ONLINE_CHECK_NOT_SUPPORTED (validation not scheduled) |
6001 | Returns error_code: MISSING_REQUIRED_INPUT (validation not scheduled) |
6002 | Returns error_code: INVALID_REQUIRED_INPUT (validation not scheduled) |
6003 | Returns error_code: MISSING_TAX_AUTHORITY_CREDENTIALS (validation not scheduled) |
7000 | HTTP 500 Internal Server Error with JSON body { "code": "INTERNAL_ERROR" } |
7001 | HTTP 400 Bad Request with JSON body { "code": "COUNTRIES_NOT_ALLOWED" } to simulate running a validation for a country that is not enabled for the tenant. |
| Any other value | Treated as invalid TIN format (validation not scheduled) |
Validation source handling
If the validation_database_source parameter is used (e.g., vies), the system applies the same source-selection and fallback logic as in production. This includes:
- Preferring VIES results where available.
- Falling back to local sources or returning appropriate errors based on input and country logic.
Example request
You can test Sandbox behavior using the TIN values described above across all supported validation endpoints:
- Works with both API v1 and v2
- Supports both single and batch validation endpoints
Below is an example using the v2 single validation endpoint with a test TIN (2000):
curl --location 'https://sandbox.fonoa.com/lookup/v2/single-validations' \
--header 'Content-Type: application/json' \
--header 'Ocp-Apim-Subscription-Key: <your-sandbox-API-key>' \
--data '{
"country_iso_code": "pl",
"tax_identification_number": "2000"
}'