Skip to main content
Version: 1.7.3

RequestPdfURLs

This method can be used to retrieve PDFs for single or multiple recipients. The PDF URL will be returned in the response only if it is already generated by us. You can use the SubmissionId or RecordIds to request the pdf URLs.

Note: The PDF URL will be returned in response only after the return is transmitted in the API. This method will not work for Inprogress returns.

How does it work?

  1. The first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the 'Bearer' token. Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

  2. The second step is to call the Create call for the particular Form endpoint and then call the Transmit call. Once the return is in Transmitted status, you can call this method to get the PDF.

  3. Next, call the [POST] FormW2C/RequestPDFURLs endpoint. You will need to supply the following parameters:

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth Authentication API)

    • Form reference (SubmissionId or RecordIds) - You can either request all the PDFs for a submission or specify RecordIs (Across submissions) of the forms you need the PDF.

    • TINMaskType - Mention whether you want the TIN (SSN) to be masked in the PDF. Only the last digits of the SSN will be visible and the rest of the digits will be crossed (xxx-xx-1234). The values for this node are,

      • Masked
      • Unmasked
      • Both (Both Masked and Unmasked copies will be returned in the URL)
POST FormW2C/RequestPdfURLs 
Run in Postman

Request Body

FieldTypeDescription
SubmissionIdGuidOptional Unique identifier of an API submission. Use this node to request the PDFs under a particular submission. If you are going to request the PDFs using the RecordIds, you can leave the SubmissionId blank or null.
RecordIdsobject[]Specify the list of RecordIds under this Array
    RecordIdGuidUnique identifier of the return.
CustomizationobjectIncludes PDF customizations
    TINMaskTypestringOptional Mention whether you want the TIN to be masked in the PDF. If masked, only the last digits of the SSN will be visible and the rest of the digits will be crossed (xxx-xx-1234).
Allowed values: "MASKED", "UNMASKED", "BOTH"

Request JSON

{
"SubmissionId": "03f83fe9-05ca-41f0-86c3-00d073528712",
"RecordIds": [
{
"RecordId": "2388983e-0215-4c99-8033-951dee1ccfef"
}
],
"Customization": {
"TINMaskType": "Both"
}
}

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
FormW2CRecordsobjectContains PDF URLs of the forms requested in the API request.
    SuccessRecordsobject[]Shows the successful records for the given submission request.
        RecordIdGuidUnique identifier of the return.
        StatusstringStatus of the PDF in TaxBandits.
  • Success - The PDF is generated and you can download it.
        FilesobjectContains multiple copies of a particular return.
            Copy1objectCopy 1: For State, City, or Local Tax Department
                UnmaskedstringLink to download the Unmasked copy
                UnmaskedPathstringThe storage path of the unmasked TIN
                MaskedstringLink to download the Masked copy
                MaskedPathstringThe storage path of the masked TIN
            Copy2objectCopy 2: To Be Filed With Employee's State, City, or Local Income Tax Return
                UnmaskedstringLink to download the Unmasked copy
                UnmaskedPathstringThe storage path of the unmasked TIN
                MaskedstringLink to download the Masked copy
                MaskedPathstringLink to download the Masked copy
            CopyBobjectCopy B: To Be Filed With Employee's FEDERAL Tax Return.
                UnmaskedstringLink to download the Unmasked copy
                UnmaskedPathstringThe storage path of the unmasked TIN
                MaskedstringLink to download the Masked copy
                MaskedPathstringThe storage path of the masked TIN
            CopyCobjectCopy C: For EMPLOYEE'S RECORDS
                UnmaskedstringLink to download the Unmasked copy
                UnmaskedPathstringThe storage path of the unmasked TIN
                MaskedstringLink to download the Masked copy
                MaskedPathstringThe storage path of the masked TIN
            CopyDobjectCopy D: For Employer
                UnmaskedstringLink to download the Unmasked copy
                UnmaskedPathstringThe storage path of the unmasked TIN
                MaskedstringLink to download the Masked copy
                MaskedPathstringThe storage path of the masked TIN
    ErrorRecordsobject[]Contains records that are errored
        RecordIdGuidUnique identification of the record.
        StatusstringStatus of the error record.
  • PDF_Not_Generated - PDF is yet to be generated. You will have to wait and send a new API request to get the PDF.
  • Not Transmitted - The return is not transmitted yet.
  • Invalid RecordId - Given record id is invalid
        MessagestringDescription of each statuses
Errorsobject[]Lists the errors in the API call
    IdstringReturns the error Id.
    NamestringName of the validation error
    MessagestringGives the detailed status message.

Response JSON

{
    "SubmissionId": "d90558f5-d7c5-4734-a467-96134fca4626",
    "FormW2Records": {
      "SuccessRecords": [
            {
                "RecordId": "8daaa39f-7955-4bc1-a4c3-3bd54020851b",
                "Status": "Success",
                "Files": {
                    "Copy1": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copy1_1up_36323837.pdf",
                    "UnmaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copy1_1up_36323837.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copy1_1up_36323837.pdf",
                        "MaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copy1_1up_36323837.pdf"
                    },
                    "Copy2": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copy2_1up_36323837.pdf",
                        "UnmaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copy2_1up_36323837.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copy2_1up_36323837.pdf",
                        "MaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copy2_1up_36323837.pdf"
                    },
                    "CopyB": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyb_1up_36323837.pdf",
                        "UnmaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyb_1up_36323837.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyb_1up_36323837.pdf",
                        "MaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyb_1up_36323837.pdf"
                    },
                    "CopyC": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyc_1up_36323837.pdf",
                        "UnmaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyc_1up_36323837.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyc_1up_36323837.pdf",
                        "MaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyc_1up_36323837.pdf"
                    },
                    "CopyD": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyd_1up_36323837.pdf",
                        "UnmaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/u/copyd_1up_36323837.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyd_1up_36323837.pdf",
                        "MaskedPath": "pdfs/f502ee15-25c8-41d0-83a6-f68794a8c9b4/099dc9ab-9f57-42f9-b4ee-968392577ff7/w2/36323837/m/copyd_1up_36323837.pdf"
                    }
                }
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}

PDF Security

The PDFs contain PII (Personally Identifiable Information) data of the recipients. To make sure that the PII data involved is completely secured, TaxBandits has added additional security to the form PDFs.

The PDF links you get in the Response are encrypted, and you will have to decrypt them before downloading.

Refer to this link for the steps to decrypt PDF with Sample codes.