Use the Compliancely Sandbox to develop and test Tax Transcript integrations without production billing or real taxpayer data. The sandbox simulates consent collection, IRS authorization, and transcript retrieval with deterministic or interactive outcomes depending on the flow you are testing.

Before you begin, review the general Sandbox guide, How Tax Transcript works.

Getting Started

Possible Statuses
Depending on the flow, a request may move through:

Pending · Consent Collected · Consent Processing · Consent Submitted · Consent Accepted By IRS · Consent Rejected · Consent Rejected By IRS · Processing · Completed · Error

See the status lifecycle for definitions.

How Simulation Works

The sandbox uses test TIN ranges and, for some flows, taxpayer actions on the consent page to produce outcomes. Outcomes fall into three categories:

Flow 1 - Tax Pro - Individual

Customer Provides All Taxpayer's Details

Applies to the Tax Pro dedicated-link flow where the taxpayer completes all required information and signs on a single consent page.

TIN ranges (Individual)

-- If chosen "I have IRS account (or) I'll create an account" in the consent link

-- If chosen "I do not want to create an IRS account"

Sandbox flow

1. Create a Tax Pro request with information_scope key as 'full' and customer_attestation_confirmed key as true.
2. A consent link will be sent to the Taxpayer. Taxpayer has to verify details and submit the signature
3. Next, Taxpayer will be redirected to the dummy IRS page
4. On the dummy IRS page -
   1. Proceeds / approves: consent is collected and the flow continues toward Completed
   2. Rejects: Request moves to Consent Rejected

Flow 2 - Tax Pro - Individual

Invite Link - Individual Verification

Applies to the IRS Tax Pro authorization path (How it works — Option 2).

Tax Pro sandbox uses the same Individual TIN ranges from the 8821 prefill documentation to enter the interactive flow. The final status is not determined by the TIN — it depends on what the taxpayer selects on the sandbox IRS approval page.

TIN ranges

-- If chosen "I have IRS account (or) I'll create an account" in the consent link

Use any TIN within these ranges when creating a Tax Pro request:

These ranges match the 8821 Individual prefill Completed ranges. In the Tax Pro flow they only start the sandbox experience — they do not force the final outcome.

-- If chosen "I do not want to create an IRS account"

Sandbox flow

1. Create an Individual Tax Transcript request.
2. Taxpayer will receive an email with the data collection link
3. The taxpayer reviews or completes the required information, and provides their electronic signature and submit.
4. Taxpayer receives another email with the IRS consent page link.
5. Upon clicking, the taxpayer is redirected to the dummy IRS Approval page for simulation.
6. On the dummy IRS Approval page, the taxpayer can choose one of the following actions:
   1. Approve – The request proceeds through processing and eventually reaches the Completed status.
   2. Reject – The request is updated to the Consent Rejected status, allowing the customer to review the rejection reason and, if necessary, update the request and initiate a new consent process.

The request will not proceed to transcript retrieval until the taxpayer approves the authorization on the IRS sandbox page.

Flow 3 - 8821 - Business

Applies to:

• Transcript request - Business and works for both Customer Provides All Taxpayer's Details and Invite Link

The final status is determined entirely by the TIN — no taxpayer interaction is required.

TIN ranges

Downloading transcript files

For details on handling the Transcript API response, refer to the documentation here

Webhooks

When webhooks are configured, sandbox requests emit the same event types as production, including:

• Consent Collected
• Consent Submitted (If it is via TaxPro)
• Consent Rejected
• Consent Rejected by IRS
• Completed

Configure sandbox webhook URLs separately from production. See Webhooks.

Moving to Production

Before switching from sandbox:

• Change the base URL to the production Compliancely endpoint.
• Use production credentials and configure production webhooks.
• Replace test TINs with real taxpayer data.
• Ensure billing is configured for your account.

See the Sandbox overview — Moving to Production.