---
updatedAt: 2025-09-08T20:08:21.000Z
agentTools:
  projectIndex: https://docs.fonoa.com/llms.txt
---

# Lookup sandbox environment

# 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

<br />

## 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.

<Table align={["left","center"]}>
  <thead>
    <tr>
      <th>
        TIN
      </th>

      <th>
        Simulated Behavior
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `1000`
      </td>

      <td>
        Valid format, not found online
      </td>
    </tr>

    <tr>
      <td>
        `2000`
      </td>

      <td>
        Valid format, found online
      </td>
    </tr>

    <tr>
      <td>
        `2100`
      </td>

      <td>
        The same result as `2000`, with 5–15s background processing delay
      </td>
    </tr>

    <tr>
      <td>
        `2101`
      </td>

      <td>
        The same result as `2000`, with 1–3s ingestion delay (to simulate SLA breach)
      </td>
    </tr>

    <tr>
      <td>
        `3000`
      </td>

      <td>
        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
      </td>
    </tr>

    <tr>
      <td>
        `5001`
      </td>

      <td>
        Valid format, returns `error_code: NETWORK_ERROR`
      </td>
    </tr>

    <tr>
      <td>
        `5002`
      </td>

      <td>
        Valid format, returns `error_code: TEMPORARY_UNAVAILABLE`
      </td>
    </tr>

    <tr>
      <td>
        `5003`
      </td>

      <td>
        Valid format, returns `error_code: UNKNOWN_RESPONSE`
      </td>
    </tr>

    <tr>
      <td>
        `5004`
      </td>

      <td>
        Valid format, returns `error_code: INCOMPLETE_IMPLEMENTATION`
      </td>
    </tr>

    <tr>
      <td>
        `5005`
      </td>

      <td>
        Valid format, returns `error_code: ONLINE_CHECK_NOT_SUPPORTED`
      </td>
    </tr>

    <tr>
      <td>
        `5006`
      </td>

      <td>
        Valid format, returns `error_code: TAX_AUTHORITY_CREDENTIALS_REJECTED`
      </td>
    </tr>

    <tr>
      <td>
        `5101`
      </td>

      <td>
        Mexico only – returns `error_code: MX_NAME_MISMATCH`
      </td>
    </tr>

    <tr>
      <td>
        `5102`
      </td>

      <td>
        Mexico only – returns `error_code: MX_ZIPCODE_MISMATCH`
      </td>
    </tr>

    <tr>
      <td>
        `5103`
      </td>

      <td>
        Mexico only – returns `error_code: MX_NAME_AND_ZIPCODE_MISMATCH`
      </td>
    </tr>

    <tr>
      <td>
        `5104`
      </td>

      <td>
        USA only – returns `error_code: TAX_AUTHORITY_SAME_TAX_ID_LIMIT_REACHED`
      </td>
    </tr>

    <tr>
      <td>
        `123456789`
      </td>

      <td>
        USA only - an individual tin to demonstrate how SSN's are masked
      </td>
    </tr>

    <tr>
      <td>
        `6000`
      </td>

      <td>
        Returns `error_code: ONLINE_CHECK_NOT_SUPPORTED` (validation not scheduled)
      </td>
    </tr>

    <tr>
      <td>
        `6001`
      </td>

      <td>
        Returns `error_code: MISSING_REQUIRED_INPUT` (validation not scheduled)
      </td>
    </tr>

    <tr>
      <td>
        `6002`
      </td>

      <td>
        Returns `error_code: INVALID_REQUIRED_INPUT` (validation not scheduled)
      </td>
    </tr>

    <tr>
      <td>
        `6003`
      </td>

      <td>
        Returns `error_code: MISSING_TAX_AUTHORITY_CREDENTIALS` (validation not scheduled)
      </td>
    </tr>

    <tr>
      <td>
        `7000`
      </td>

      <td>
        HTTP 500 Internal Server Error with JSON body `{ "code": "INTERNAL_ERROR" }`
      </td>
    </tr>

    <tr>
      <td>
        `7001`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        Any other value
      </td>

      <td>
        Treated as **invalid TIN format** (validation not scheduled)
      </td>
    </tr>
  </tbody>
</Table>

<br />

### 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.

<br />

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