1. IRS Tax Pro Flow -

Available only for Individual entity type. Default Flow for Individual requests.

Note
After a transcript request is created, Compliancely returns a secure consent URL. The customer can either share the consent URL directly with the taxpayer or configure Compliancely to send the consent email automatically. The taxpayer then reviews or enters the required information, provides their electronic signature, and completes the authorization.

Flow 1 - Successful Authorization - Customer Provided Full Details

Option 1 : Taxpayer Has (or Will Create) an IRS Account

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Create Transcript Request
    API-->>C: Request ID + Consent URL

    Note over C,TP: Customer may share the consent URL directly<br/>or Compliancely can email it to the taxpayer.

    alt Customer shares the link
        C->>TP: Share Consent URL
    else Compliancely sends email
        API->>TP: Send Consent Email
    end

    TP->>API: Open Consent Link
    TP->>API: Verify / Complete Information
    TP->>API: Provide Electronic Signature

    TP->>API: Select "I have an IRS account"<br/>or "Create an IRS account" and submit
    API-->>C: Webhook trigger - Consent Collected

		API->>IRS: Redirect to IRS Login
 		TP->>IRS: Sign in / Create IRS Account
    
    TP->>IRS: Authenticate and Authorize
    
    C->>API: Retrieve Request Status (Optional)

    IRS-->>API: If Authorization Approved

    API->>IRS: Retrieve Tax Transcript
    IRS-->>API: Transcript Data Retrieved

    API-->>C: Webhook trigger - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JSON

Option 2 – Taxpayer Does Not Have an IRS Account

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Create Transcript Request
    API-->>C: Request ID + Consent URL

    Note over C,TP: Customer may share the consent URL directly<br/>or Compliancely can email it to the taxpayer.

    alt Customer shares the link
        C->>TP: Share Consent URL
    else Compliancely sends email
        API->>TP: Send Consent Email
    end

    TP->>API: Open Consent Link
    TP->>API: Verify / Complete Information
    TP->>API: Provide Electronic Signature

    TP->>API: Select "I do not have an IRS account" and submit
    API-->>C: Webhook trigger - Consent Collected
    
    C->>API: Retrieve Request Status (Optional)

    Note over API,C: Compliancely processes the authorization on behalf of the taxpayer.

    IRS-->>API: If IRS Approved the Authorization

		IRS-->>API: Transcript Data Retrieved


    API-->>C: Webhook - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JSON

Flow 2 - Successful Authorization - Invite Link

Option 1 : Taxpayer Has (or Will Create) an IRS Account

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Generate Invite Link (Name & Email)
    API->>TP: Send Invitation Email

    TP->>API: Open Invite Link
    TP->>API: Enter Remaining Information
    TP->>API: Provide Electronic Signature
    TP->>API: Select "I have an IRS account or I will signup" and submit
    
		API-->>C: Webhook trigger - Consent Collected
    
    API-->>IRS: Submits the data to IRS
		Note over API,IRS: Compliancely submits the data to IRS.
    
    API-->>TP: Sends an email with the IRS link
    
		API-->>C: Webhook trigger - Consent Submitted

    
    API->>IRS: Redirect to IRS Login
 		TP->>IRS: Sign in / Create IRS Account

		TP->>IRS: Authenticate and Authorize
    
    C->>API: Retrieve Request Status (Optional)

    IRS-->>API: If Authorization Approved

    API->>IRS: Retrieve Tax Transcript
    IRS-->>API: Transcript Data Retrieved

    API-->>C: Webhook trigger - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JS

Option 2 – Taxpayer Does Not Have an IRS Account

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Generate Invite Link (Name & Email)
    API->>TP: Send Invitation Email

    TP->>API: Open Invite Link
    TP->>API: Enter Remaining Information
    TP->>API: Review IRS Form 8821 details
    TP->>API: Provide Electronic Signature
		TP->>API: Select "I do not have an IRS account or I will signup" and submit
    
		API-->>C: Webhook trigger - Consent Collected

    API->>IRS: Submit IRS Form 8821

    Note over API,IRS: Processing in progress

    C->>API: Retrieve Request Status (Optional)

    IRS-->>API: Tax Transcript Available

    API-->>C: Webhook trigger - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JSON

Flow 3 - Authorization Rejected - For an Individual

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Create Transcript Request
    API-->>C: Request ID + Consent URL

    Note over C,TP: Customer may share the consent URL directly<br/>or Compliancely can email it to the taxpayer.

    C->>TP: Share Consent URL (Optional)
    API->>TP: Send Consent Email (Optional)

    TP->>API: Open Consent Link
    TP->>API: Fill or Verify Information
    TP->>API: Provide Electronic Signature and submit
    API-->>C: Webhook trigger - Consent Collected
		C->>API: Retrieve Request Status (Optional)

    API->>IRS: Redirect to IRS Login
    TP->>IRS: Authenticate and Authorize

    IRS-->>API: Authorization Rejected

    API-->>C: Rejection Email
    API-->>C: Webhook trigger - Rejection

    Note over C,TP: Customer contacts the taxpayer to understand the rejection reason.

    alt Information needs correction
        C->>API: Transcript Update API
        API-->>TP: New Consent Link
        TP->>API: Open Updated Consent Link
        TP->>API: Verify Information
        TP->>API: Provide Signature and submit
        
        API-->>C: Webhook trigger - Consent Collected
				C->>API: Retrieve Request Status (Optional)


        API->>IRS: Redirect to IRS Login
        TP->>IRS: Authenticate and Authorize
				Note over API,IRS: Depending on the authorization, accepted or rejected cycles will continue.
    	
    end

2. IRS Form 8821

Applicable for Business entity type and optionally for individual entity type

Note
After a transcript request is created, Compliancely returns a secure consent URL. The customer can either share the consent URL directly with the taxpayer or configure Compliancely to send the consent email automatically. The taxpayer then reviews or enters the required information, provides their electronic signature, and completes the authorization.

Flow 1 - Customer-Provided Information

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Create Transcript Request (All or Partial Information)
    API-->>C: Request ID + Consent URL

    Note over C,TP: Customer may share the consent URL directly<br/>or Compliancely can email it to the taxpayer.

    alt Customer shares the link
        C->>TP: Share Consent URL
    else Compliancely sends email
        API->>TP: Send Consent Email
    end

    TP->>API: Open Consent Link
    TP->>API: Verify / Complete Information
    TP->>API: Review IRS Form 8821 details
    TP->>API: Provide Electronic Signature and Submit
    
		API-->>C: Webhook trigger - Consent Collected

    API->>IRS: Submit IRS Form 8821

    Note over API,IRS: Processing in progress

    
    C->>API: Retrieve Request Status (Optional)

		IRS-->>API: Tax Transcript Available

		API-->>C: Webhook trigger - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JSON

Flow 2 - IRS Form 8821 (Invite Link)

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    C->>API: Generate Invite Link (Name & Email)
    API->>TP: Send Invitation Email

    TP->>API: Open Invite Link
    TP->>API: Enter Remaining Information
    TP->>API: Review IRS Form 8821
    TP->>API: Provide Electronic Signature and Submit
    
		API-->>C: Webhook trigger - Consent Collected

    API->>IRS: Submit IRS Form 8821

    Note over API,IRS: Processing in progress

    C->>API: Retrieve Request Status (Optional)

    IRS-->>API: Tax Transcript Available

    API-->>C: Webhook trigger - Completed

    C->>API: Retrieve Transcript API
    API-->>C: Transcript Details / PDF / JSON

Flow 3 - Rejection / Resubmission

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant TP as Taxpayer
    participant IRS as IRS

    API->>IRS: Submit IRS Form 8821

    Note over API,IRS: Request is being processed

    alt Transcript Available
        IRS-->>API: Transcript Available
        API-->>C: Webhook trigger - Completed

    else Request Rejected

        API-->>C: Rejection Email
        API-->>C: Webhook trigger - Rejection

        Note over C,TP: Customer contacts the taxpayer to understand the rejection reason.

        alt Taxpayer information requires correction
            C->>API: Update Transcript Request API
            API-->>TP: Generate New Consent Link

            TP->>API: Open New Consent Link
            TP->>API: Verify / Update Information
            TP->>API: Provide Electronic Signature and submit

            API->>IRS: Resubmit IRS Form 8821

        else No transcript available within cutoff period

            Note over API,C: The request is closed after the configured cutoff period.
						API-->>C: Webhook trigger - Rejection
        end
    end

3. Own CAF

How the Own CAF Flow Works

The Own CAF flow allows you to use your own CAF number to request taxpayer transcripts through Compliancely.

Unlike the Zenwork CAF flow, where Compliancely manages the consent and CAF submission process, the Own CAF flow uses IRS OAuth authorization associated with your CAF.

Important: The taxpayer and Client Account are two different entities in this flow.

Key Concepts

Taxpayer

The taxpayer is the individual or business whose tax transcripts you want to retrieve.

The taxpayer is identified by the information provided when creating the transcript record, primarily:

TIN
Taxpayer name

Client Account

A Client Account is not the taxpayer.

It represents a designee/sub-account under your Compliancely integration. It can be used when you manage multiple designees, where each designee may have their own:

CAF number
Address
PTIN
IRS OAuth authorization

When using Client Accounts, the OAuth authorization and transcript processing are associated with the specific Client Account.

Standard Own CAF Flow (No Client Account)

This is the simplest flow when you are using a single CAF and do not need Client Accounts.

Who Should Use This?

Use the Standard Own CAF flow if your organization:

Uses a single CAF for Tax Transcript requests.
Has one primary designee/IRS authorization and want to associate with the Compliancely account.
Does not need to maintain separate CAFs or IRS authorizations for different designees.
Wants all ISP transcript requests to be processed using the same account-level IRS authorization.

Example: Your organization has one CAF and one authorized designee responsible for retrieving transcripts for all taxpayers.

How it Works?

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant IRS as IRS

    C->>API: Create transcript Record<br/>TIN + Name + CAF
    API-->>C: transcript Record ID

    C->>IRS: Complete OAuth Authorization
    IRS-->>C: OAuth Token

    C->>API: Queue transcript Record
    API->>IRS: Request Transcripts using OAuth
    IRS-->>API: Transcript Data

    API-->>C: Status = Completed
    C->>API: Retrieve transcript / Transcript
    API-->>C: Transcript Data / PDFs

Step 1: Create an transcript Record

Create an transcript record with the taxpayer's information and your CAF details.

POST /api/v1/transcript/isp/create/

Provide:

Taxpayer TIN
Taxpayer name
Your CAF
required_forms (optional, depending on the transcript requirements)
add_to_queue if you want to queue the request immediately

Important: The taxpayer's TIN and name must be provided here. Do not use a Client Account ID as the taxpayer identifier.

Step 2: Complete IRS OAuth Authorization

Complete the IRS OAuth authorization using your IRS account.

The OAuth token authorizes Compliancely to make the required IRS requests using your CAF.

The authorization is associated with your user account when using the standard Own CAF flow.

Step 3: Add the Transcript Record to the Queue

You can queue the transcript record in either of two ways.

Option A - Queue during creation

Set:

{
  "add_to_queue": true
}

Option B — Queue after creation

POST /api/v1/transcript/isp/add-to-queue/

Once the record is successfully queued and OAuth authorization is available, Compliancely begins transcript processing.

Step 4: Transcript Processing

Compliancely processes the request using the authorized IRS OAuth token.

Processing begins automatically after the OAuth token is successfully generated and the transcript record is queued.

The request is processed periodically until the requested forms are completed.

Step 5: Retrieve the Results

When all requested forms and PDFs have been processed, the request moves to Completed.

You can then retrieve the transcript information from the transcript/request details.

Own CAF with Client Account

Client Accounts are useful when your organization manages multiple designees, each with their own CAF and IRS authorization.

The overall flow is similar, but the CAF and OAuth authorization are associated with the specific Client Account.

Who Should Use This?

Use the Own CAF with Client Account flow if your organization manages multiple designees, where each designee needs their own CAF information and IRS authorization.

This flow is appropriate if you:

Have multiple designees with different CAF numbers.
Need to maintain a separate IRS authorization for each designee.
Want transcript requests to be processed using the CAF and IRS authorization of a specific designee.
Want to generate an IRS authorization URL for each designee and either share it directly or integrate it into your own application for the designee to complete authorization.

When requesting a taxpayer's transcript, you associate the transcript request with the appropriate Client Account. Compliancely then processes that request using the CAF and IRS authorization associated with that designee.

📘
Remember
A Client Account represents your designee, not the taxpayer. The taxpayer whose transcripts are being requested is identified separately by the TIN and name in the transcript request.

How it Works?

sequenceDiagram
    participant C as Customer
    participant API as Compliancely
    participant IRS as IRS

    C->>API: Create / Select Client Account
    API-->>C: Client Account ID

    C->>API: Create transcript for Client Account<br/>TIN + Name + Client Account
    API-->>C: transcript Record ID

    C->>IRS: Complete OAuth for Client Account
    IRS-->>C: OAuth Token

    C->>API: Queue transcript Record
    API->>IRS: Request Transcripts<br/>using Client Account OAuth
    IRS-->>API: Transcript Data

    API-->>C: Status = Completed
    C->>API: Retrieve Transcript
    API-->>C: Transcript Data / PDFs

How Client Accounts Change the Flow

When using a Client Account:

The Client Account provides the CAF.
OAuth authorization is associated with the Client Account.
Queue processing uses the Client Account's OAuth authorization.
The taxpayer is still identified by the TIN and name in the transcript create request.

IRS Authorization

When using the Client Account model, the IRS authorization URL must be generated for the correct client_account_id. The resulting OAuth authorization and subsequent transcript processing are scoped to that Client Account.

A redirect_url is required when generating the authorization URL. It specifies where Compliancely should redirect the designee after the IRS authorization process is completed, allowing the designee to seamlessly return to the appropriate page in the customer's application.

Step 1: Create a Client Account

Create a Client Account to represent the designee whose CAF and IRS authorization will be used for transcript retrieval.

POST /api/v1/transcript/clientaccount/

The Client Account contains information such as:

CAF number
Address
PTIN
Other designee information

The Client Account ID is used in subsequent API calls.

Step 2: Create an Transcript Record for the Client Account

Create the ISP record using the taxpayer's information and associate it with the Client Account.

POST /api/v1/transcript/isp/create/

Provide:

Taxpayer TIN
Taxpayer name
Client Account ID
Required forms, if applicable

📘
Important
The Client Account ID identifies the designee/CAF. It is not the taxpayer identifier. The taxpayer is always identified by the TIN and name provided in the ISP request.

Step 3: Add the Transcript Record to the Processing Queue

You can queue the ISP record either while creating it or after creation.

Option A - Queue during creation

Set:

{
  "add_to_queue": true
}

Option B — Queue after creation

POST /api/v1/transcript/isp/add-to-queue/

Step 4: Generate the IRS Authorization URL

Generate an IRS authorization URL for the Client Account. The authorization URL allows the designee associated with that Client Account to sign in to the IRS and authorize access using their IRS credentials.

POST /api/v1/transcript/get-irs-isp-authorization-url/

The customer can use the generated authorization URL in either of the following ways:

Share the URL directly with the designee.
Integrate the URL into their own application or UI, allowing the designee to initiate the IRS authorization process as part of the customer's workflow.

The designee opens the authorization URL, signs in to their IRS account, and completes the required authorization. Once successfully completed, the resulting IRS authorization is associated with the corresponding Client Account.

Important: Always generate the authorization URL using the correct client_account_id. The authorization is scoped to that Client Account and will be used when processing transcript requests associated with it.

Step 5: Transcript Processing

Compliancely processes the request using the OAuth authorization associated with the Client Account.

The request is processed periodically until all requested forms and transcripts are completed.

Step 6: Retrieve the Transcript

Once processing is complete, the request moves to Completed and the transcript data becomes available.

GET /api/v1/transcript/?id=<id>

You can then retrieve the available transcript information and PDFs.