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"
}'