Sandbox Access and Simulation
TaxBandits Sandbox environment provides a secure and controlled testing space to integrate, validate, and refine your API workflows without impacting real filings or data.
This section outlines how to configure sandbox access, authenticate requests, and use simulation tools to test various filing scenarios and API outcomes.
Accessing Sandbox
To begin using the sandbox environment, follow these steps:
1. Register and Retrieve Credentials
Access the TaxBandits Sandbox Developer at https://sandbox.taxbandits.com/ and obtain the following credentials: Client ID, Client Secret & User Token.
These credentials are specific to the sandbox and should not be reused in the production environment.
2. Authenticate via OAuth
Use the OAuth 2.0 authentication flow to request a JWT (access token). This access token must be included in the Authorization header of subsequent API calls.
All sandbox authentication requests should be made to: https://testoauth.expressauth.net/v2/tbsauth
3. Use the Access Token to Send API Requests
Once you’ve successfully authenticated, you’ll receive a JWT (access token) that remains valid for 60 minutes. This token must be included in the Authorization header of all subsequent API requests.
All API requests in the sandbox should target: https://testapi.taxbandits.com/v1.7.3/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3
MiOiJ0ZXN0YXBpLnRheGJhbmRpdHMuY29tIiwiYXVkI
joiYTU3NGI3NWYxOGIyNGZjMDlmOTAzOWZmYjVjYjA4ZjMiLCJp
YXQiOjE1OTU5MjAxMjQsImV4cCI6MTU5NTkyNzMyNH0.BIg8764SOhOai9As
3uRSidrF1-B9CxL6D5z4OggcVbs
Content-Type: application/json
Requests made to this base URL will operate solely within the sandbox environment and will not impact live data or systems.
Simulations
Our Sandbox environment supports various simulations to help you test your integration across different scenarios—from form status handling to TIN verification logic. These simulations ensure your application is ready for both standard and edge-case outcomes before moving to production.
1. Form Status Simulation
Form Status Simulation allows you to test the complete lifecycle of a return—from transmission to acceptance, rejection, or partial success—based on predefined test data.
By assigning specific TINs to payers in the Sandbox, you can simulate various outcomes for W-2, 1099, and 94x forms. This helps you verify your system’s behavior when returns are accepted, rejected (with specific IRS error codes), or accepted with errors.
View Form Status Simulation Guide
2.TIN Matching Simulation
The TIN Matching Simulation allows you to test how your application handles various TIN Matching outcomes when using the TaxBandits API in the sandbox environment. It’s designed to help you simulate and observe webhook behavior and status transitions without triggering real IRS validations. In this simulation, specific TIN patterns are used to generate predictable outcomes:
- TINs ending in triple zeroes (e.g., 12-3456000) will simulate a "Failed" TIN match.
- All other TINs will simulate a "Success" status.
This simulation is applicable whether TIN Matching is performed as part of a W-9 submission or through the TinMatchingRecipients endpoint.
Note: To test webhook responses, ensure the TIN Matching Status Change Webhook is configured in your sandbox account.
View TIN Matching Simulation Guide
3.Real-Time TIN Matching Simulation
This simulation enables a more granular test of real-time TIN Matching outcomes. Depending on the last digit of the TIN, you can simulate different IRS validation statuses such as:
- Success – Matching SSN, EIN, or both
- Failure – Invalid or unissued TIN, mismatch, duplicates
- On Hold – Triggered after repeated failed attempts