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 FormW2G/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" |
Request JSON
- Sample 1
- Sample 2
- Sample 3
{
"SubmissionId": "9042f8a6-903c-4c6d-8f64-787702bf9423",
"RecordIds": [
{
"RecordId": "e6270427-42a2-46fc-8d90-29a0f5d975e9"
}
],
"Customization": {
"TINMaskType": "Both"
}
}
{
"SubmissionId": "a863c015-91f1-4128-84fc-bb38922b80f9",
"RecordIds": [
{
"RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
},
{
"RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
}
],
"Customization": {
"TINMaskType": "Masked"
}
}
{
"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. |
| FormW2GRecords | 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 |
| MaskedPath | 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: File this copy with your state, city, or local income tax return, when required. |
| 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: Report this income on your federal tax return. If this form shows federal income tax withheld in box 4, attach this copy to your 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 Recipient'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 Payer |
| 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 |
| ErrorRecords | object[] | Contains the error records |
| RecordId | Guid | Unique identifier of the return. |
| Status | string | Status of the error record.
|
| 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
- Response 2
- Response 3
{
"SubmissionId": "d90558f5-d7c5-4734-a467-96134fca4626",
"FormW2GRecords": {
"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
}
{
"SubmissionId": null,
"FormW2GRecords": {
"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
}
{
"SubmissionId": null,
"FormW2GRecords": {
"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.