RequestPdfUrls

RequestPdfUrls

This endpoint can be used to retrieve the PDF copies of W-2G correction forms for either a single recipient or multiple recipients. You can request the PDF URLs by providing either the SubmissionId or the RecordIds associated with the returns.

Key points

• This endpoint does not generate new PDFs. It only retrieves the links for PDFs that are already created in the system.
• The PDF URLs will be returned in the response only if they have already been generated by TaxBandits.

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] Form W-2G Correction/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 RecordIds (Across submissions) of the forms you need the PDF.
   • TINMaskType: specify how the SSN should appear in the PDF. Available values:
     • Masked – Only the last four digits of the SSN are shown (xxx-xx-1234).
     • Unmasked – Full SSN is displayed.
     • Both – Returns both masked and unmasked versions of the PDF.

POST FormW2GCorrection/RequestPdfUrls 

Run in Postman

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, then leave the SubmissionId blank or null.
RecordIds	object[]	Specify the list of RecordIds under this Array.
RecordId	Guid	Unique identifier of the return.
Customization	object	Includes 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"

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
FormW2GCorrectionRecords	object	Contains PDF URLs of the forms requested in the API request.
SuccessRecords	object[]	Shows the successful records for the given submission request.
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 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 recipient’s state 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: For Recipient
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 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
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.
SequenceId	string	An unique reference ID for the submission that can be used to identify a particular record. The Sequence ID will be returned in the Response for your reference.
RecordId	Guid	Unique identifier of a record
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
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

Request Params

{
 "SubmissionId": "94677293-8ecf-443b-8a76-8b8d192b2cb1}",
 "RecordIds": [
   {
     "RecordId": "97c9ba31-c244-4aeb-addc-f1b53be373fc"
   }
 ],
 "Customization": {
   "TINMaskType": "Both"
 }
}

Response Json

Success Response - This is a sample response for successful API requests.

{
    "SubmissionId": "97c9ba31-c244-4aeb-addc-f1b53be373fc",
    "FormW2GCorrectionRecords": {
        "SuccessRecords": [
            {
                "RecordId": "97c9ba31-c244-4aeb-addc-f1b53be373fc",
                "Status": "Success",
                "Files": {
                    "Copy1": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copy1_1up_3142187.pdf",
                        "UnmaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copy1_1up_3142187.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copy1_1up_3142187.pdf",
                        "MaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copy1_1up_3142187.pdf"
                    },
                    "Copy2": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copy2_1up_3142187.pdf",
                        "UnmaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copy2_1up_3142187.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copy2_1up_3142187.pdf",
                        "MaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copy2_1up_3142187.pdf"
                    },
                    "CopyB": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyb_1up_3142187.pdf",
                        "UnmaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyb_1up_3142187.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyb_1up_3142187.pdf",
                        "MaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyb_1up_3142187.pdf"
                    },
                    "CopyC": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyc_1up_3142187.pdf",
                        "UnmaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyc_1up_3142187.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyc_1up_3142187.pdf",
                        "MaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyc_1up_3142187.pdf"
                    },
                    "CopyD": {
                        "Unmasked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyd_1up_3142187.pdf",
                        "UnmaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/u/copyd_1up_3142187.pdf",
                        "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyd_1up_3142187.pdf",
                        "MaskedPath": "pdfs/9f64ef0b-80f7-4c09-9d95-6f26109fa73e/794451d1-909a-4ffa-852a-fa567b391e15/1099/3142187/m/copyd_1up_3142187.pdf"
                    }
                }
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}