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.

POST FormW2/RequestPdfURLs 

Request Body

Field	Type	Description
SubmissionId	Guid	Optional 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.
RecordIds	object[]	Contains the list of RecordIds for which you are requesting the pdf URLs
RecordId	Guid	Unique identifier of the return.
Customization	object	Contains PDF customizations
TINMaskType	string	Optional 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&quot

Request JSON

Sample 1

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

Sample 2

{
 "SubmissionId": "a863c015-91f1-4128-84fc-bb38922b80f9",
 "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ],
 "Customization": {
   "TINMaskType": "Masked"
 }
}

Sample 3

{
   "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ]
}

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
FormW2Records	object	Contains success and error records of the requested RecordIds.
SuccessRecords	object[]	Contains the successful records with pdf urls if the forms are generated.
RecordId	Guid	Unique identifier of the return.
Status	string	Status of the PDF in TaxBandits. Success - The PDF is generated and you can download it.
Files	object	Contains multiple copies of a particular return.
Copy1	object	Copy 1: For State, City, or Local Tax Department
Unmasked	string	Link to download the Unmasked copy
UnmaskedPath	string	The storage path of the unmasked TIN
Masked	string	Link to download the Masked copy
MaskedPath	string	The storage path of the masked TIN
Copy2	object	Copy 2: To Be Filed With Employee’s State, City, or Local Income Tax Return
Unmasked	string	Link to download the Unmasked copy
UnmaskedPath	string	The storage path of the unmasked TIN
Masked	string	Link to download the Masked copy
MaskedPath	string	The storage path of the masked TIN
CopyB	object	Copy B: To Be Filed With Employee’s FEDERAL Tax Return.
Unmasked	string	Link to download the Unmasked copy
UnmaskedPath	string	The storage path of the unmasked TIN
Masked	string	Link to download the Masked copy
MaskedPath	string	The storage path of the masked TIN
CopyC	object	Copy C: For EMPLOYEE’S RECORDS
Unmasked	string	Link to download the Unmasked copy
UnmaskedPath	string	The storage path of the unmasked TIN
Masked	string	Link to download the Masked copy
MaskedPath	string	The storage path of the masked TIN
CopyD	object	Copy D: For Employer
Unmasked	string	Link to download the Unmasked copy
UnmaskedPath	string	The storage path of the unmasked TIN
Masked	string	Link to download the Masked copy
MaskedPath	string	LThe storage path of the masked TIN
ErrorRecords	object[]	Contains the error records
RecordId	Guid	Unique identifier of the return.
Status	string	Status 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
Message	string	Description of each statuses
Errors	object[]	Lists the errors in the API call
Id	string	Returns the error Id.
Name	string	Name of the validation error
Message	string	Description of the validation error

Response JSON

Response 1

{
    "SubmissionId": "d90558f5-d7c5-4734-a467-96134fca4626",
        "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
}

Response 2

{
   "SubmissionId": null,
   "FormW2Records": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "Errors": null
}

Response 3

{
   "SubmissionId": null,
   "FormW2Records": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "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.