Compliancely supports multiple workflows for retrieving IRS tax transcripts, allowing you to choose the integration that best fits your business process.
Before proceeding, read the sandbox overview to learn about the prerequisites for using the Compliancely Sandbox.
New to Tax Transcript?If you're unfamiliar with the transcript authorization process, start with How Tax Transcript Works before continuing.
This guide helps you:
- Choose the appropriate integration flow.
- Identify the APIs required for each flow.
- Understand the sequence in which APIs should be called.
- Learn when to poll for results or rely on webhooks.
Choose Your Integration
| Option | Authorization Managed By | Best For |
|---|---|---|
| Option 1. IRS Tax Pro (Customer-Provided Information) | Compliancely | Customers who already have the taxpayer's information |
| Option 2. IRS Tax Pro (Taxpayer Invite Link) | Compliancely | Customers who want the taxpayer to complete the information |
| Option 3. IRS Form 8821 (Using Your Own CAF) | Customer | Customers who already have their own CAF and IRS authorization process |
To understand the completely on how each flow works, please refer to the doc
IRS Tax Pro Flow - Individual
| Flow | API Reference |
|---|---|
| Customer Provided Full Details | https://apideveloper.compliancely.com/reference/api_v1_transcript_individual_create |
| Invite Link | https://apideveloper.compliancely.com/reference/api_v1_transcript_invite-link_create |
| Update request on Rejection | https://apideveloper.compliancely.com/reference/api_v1_transcript_individual_update Applicable only if the request is from Invite Link |
IRS Form 8821 - Business
APIs for Customers CAF
| Flow | API Reference |
|---|---|
| Create a Transcript Request under a Client Account | https://apideveloper.compliancely.com/reference/api_v1_transcript_client-account_isp_create_create |
| Create a Transcript Request | https://apideveloper.compliancely.com/reference/api_v1_transcript_isp_create_create |
| Add Records to Queue | https://apideveloper.compliancely.com/reference/api_v1_transcript_isp_add-to-queue_create |
| Build IRS Authorization URL | |
| Check the IRS Session Status |
Client Account APIs
Common APIs
These APIs are used in almost every integration.
| Purpose | API References |
|---|---|
| Authenticate | https://apideveloper.compliancely.com/reference/api_v2_token_create |
| Retrieve Request | https://apideveloper.compliancely.com/reference/api_v1_transcript |
| Retrieve Transcript JSON | https://apideveloper.compliancely.com/reference/api_v1_transcript_record_json_list |
| Retrieve Advanced JSON | https://apideveloper.compliancely.com/reference/api_v1_transcript_detail_create |
Integration Steps - Zenwork CAF
The following sequence describes a typical integration when using Compliancely's CAF for transcript retrieval.
Step 1: Authenticate
Obtain an access token using your API credentials. The access token must be included in the Authorization header for all subsequent API requests.
Output
- Access Token
- Token Expiration
Step 2: Create a Transcript Request
Create a transcript request for either an individual or a business taxpayer.
You can choose one of the following consent collection methods:
- Customer-Provided Information – Submit all or part of the taxpayer's information. Compliancely generates a consent link that can either be emailed to the taxpayer or shared directly by your application.
- Invite Link – Provide the taxpayer's basic information (such as name and email address). Compliancely sends an invitation email containing the consent link, allowing the taxpayer to complete the remaining information.
API Endpoints - Customer Provided Full Detail (or) Invite Link
The API returns:
- Request ID
- Consent URL
- Initial Status
Store the Request ID, as it is required to retrieve the request status and transcript results later.
Step 3: Collect Taxpayer Authorization
After the transcript request is created, the taxpayer must complete the authorization process.
Depending on your integration:
- Share the Consent URL directly with the taxpayer, or
- Allow Compliancely to send the consent email automatically.
The taxpayer will:
- Open the consent link.
- Verify or complete the required information.
- Provide their electronic signature.
- Choose their preferred authorization method.
- Complete the authorization process.
No additional API calls are required during this step.
Step 4: Monitor Request Status
After the taxpayer submits the authorization, Compliancely begins processing the request.
You can monitor progress using either:
- Webhooks (Recommended) – Receive automatic notifications when the request status changes.
- Polling – Periodically retrieve the request status using the Retrieve API.
Continue checking until the request reaches a terminal status such as Completed or Rejected.
Step 5: Handle Rejected Requests
If the request is rejected due to incorrect taxpayer information or another correctable issue:
- Review the rejection reason received through the webhook or Retrieve API.
- Correct the required information.
- Update the transcript request.
After a successful update, Compliancely generates a new consent link. The taxpayer must review the updated information, provide their signature again, and complete the authorization process before processing resumes.
Step 6: Retrieve the Completed Transcript
When the request status changes to Completed, retrieve the transcript details.
API Endpoint - Retrieve Request
The response includes transcript metadata, processing status, download links, and other related information.
Step 7: Retrieve Standard Transcript JSON (Optional)
If your application requires structured transcript data instead of PDF documents, retrieve the transcript in JSON format.
API Endpoint - Retrieve Transcript JSON
This endpoint returns the parsed transcript data for programmatic consumption.
Step 8: Retrieve Advanced Transcript JSON (Optional)
For applications that require additional transcript attributes or an enriched JSON response, use the Advanced Transcript JSON endpoint.
API Endpoint - Retrieve Advanced JSON
This endpoint provides a more comprehensive JSON representation of the transcript for advanced integrations.
Integration Steps - Customer CAF
The following sequence describes a typical integration when using your own IRS CAF (Centralized Authorization File). In this workflow, your organization manages the IRS authorization process independently, while Compliancely retrieves and delivers the requested transcripts after authorization has been granted.
Step 1: Create a Client Account (Optional)
If you expect to request transcripts for the same taxpayer multiple times or need to monitor by clients, you can create a Client Account to store their information. This avoids sending the taxpayer details with every transcript request and simplifies future integrations.
If you only need a one-time transcript request, you may skip this step and create an ISP record directly.
API Endpoints - Create Client Account
Response
The Create Client Account API returns a Client Account ID, which can be used when creating future ISP records.
Step 2: Create an ISP Record
An ISP (Information Sharing Party) Record represents the taxpayer authorization used for transcript retrieval.
Depending on your workflow, you can either:
- Create an ISP record directly by providing the taxpayer information, or
- Associate the ISP record with an existing Client Account.
API Endpoints - Without a Client Account (or) Using an Existing Client Account
Response
The API returns an ISP Record ID, which is required when requesting transcript retrieval.
Step 3: Queue Transcript Retrieval
After the taxpayer has authorized access through your own IRS CAF process, request transcript retrieval by adding the ISP record to the processing queue.
API Endpoint - Add Transcript to Queue API
Response
- Request ID
- Initial Status
Store the Request ID, as it is required to monitor processing and retrieve transcript results.
Step 4: Monitor Request Status
Once the request has been queued, Compliancely begins retrieving the transcript.
You can monitor progress by:
- Configuring Webhooks (Recommended) to receive status updates automatically, or
- Polling the Retrieve API periodically.
API Endpoint - Retrieve Request API
Continue checking until the request reaches a terminal status such as Completed or Rejected.
Step 5: Retrieve Transcript JSON
After the request reaches the Completed status, retrieve the transcript data in JSON format.
API Endpoint - Transcript JSON API
The response contains the structured transcript data for your application to consume.
Developer Notes
- Creating a Client Account is optional but recommended for recurring taxpayers.
- Every transcript retrieval request requires an ISP Record.
- Store both the Client Account ID (if used) and the Request ID returned by the APIs.
- Use Webhooks for real-time status updates whenever possible. Polling should be used only when webhook integration is not available.