RequestDraftPdfUrl

This API request will return the Draft PDF of the forms that are not transmitted yet for review purpose. The draft PDF will have copy A of the form with For Review Only watermark text.

Note: You can only retrieve PDF of a single record/form using this method.

How does it works?

1. Call the [POST] FormW2/RequestDraftPdfUrl endpoint. You will need to supply the following parameters:

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

   • Request Parameters: Specify the RecordId for the form you need the Draft PDF form. If you do not have the RecordId, then you request the PDF using the following parameters

     • Business Reference - Use the business reference PayerRef or BusinessId or EIN.
     • Employee Reference - Use the recipient reference EmployeeId or SSN.
     • Tax Year - Tax year of the form you are requesting the PDF.

POST FormW2/RequestDraftPdfUrl 

Request Body

Field	Type	Description
RecordId	Guid	Optional Specify the RecordId of the return
TINMaskType	string	Optional TIN Mask type on the TIN printed on the PDF Allowed values: "MASKED", "UNMASKED"
TaxYear	string	Optional Tax Year of the return. Specify only if you do not have the RecordId Allowed values: "2022","2023","2024"
Business	object	Optional Collects the Business identifier TIN or TBS Business Id or PayerRef. This object information is required only if you do not have the RecordId
BusinessId	Guid	Optional TaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
PayerRef	string	Optional Unique payer identifier assigned by the client. Size Range: 1 to 50
EIN	string	Optional Employer Identification Number. Use this as an alternative for BusinessId or PayerRef. Size Range: 9 to 10
Employee	object	Optional Collects the employee's unique identifier. This object information is required only if you do not have the RecordId
EmployeeId	Guid	Optional Unique Employee Identifier generated by TaxBandits
SSN	string	Optional Social Security Number. Use this as an alternative for EmployeeIds. Size Range: 9 to 11

Response Body

Field	Type	Description
RecordId	Guid	Unique identifier of the record
EmployeeId	Guid	Unique Employee Identifier generated by TaxBandits
DraftPdfUrl	string	URL of the Draft PDF
DraftPdfPath	string	Storage path of the draft PDF
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error

Payload

Request Json

Sample	Description	Action
Sample 1	To generate Draft PdfUrl With just the RecordId
Sample 2	To generate Draft PdfUrl With No RecordId

Sample 1

{
 "TaxYear": null,
 "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
 "TINMaskType":"Masked",
 "Business": null,
 "Employee": null
}

Response Json

Response	Description	Action
Response 1	Draft PdfUrl will be generated for the given RecordId.
Response 2	Draft PdfUrl will be generated for the given BusinessId and EmployeeId.

Response 1

{
    "RecordId": "5ce0a501-ddcd-4b23-af7c-c836bc434bda",
    "RecipientId": "ba15c63a-e191-4dbc-9156-457f0980052e",
    "PayeeRef": null,
    "DraftPdfUrl": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/c2d66a8c-3cf3-4dbc-9095-38b92fc58866/0927361d-25ec-47d5-9c37-7a239ec6a2fa/1099/19455581/d/copy_tbs_wm_1up_9455960000.pdf",
    "DraftPdfPath": "pdfs/c2d66a8c-3cf3-4dbc-9095-38b92fc58866/0927361d-25ec-47d5-9c37-7a239ec6a2fa/1099/19455581/d/copy_tbs_wm_1up_9455960000.pdf",
    "Error": null
  }

Node.js

Python

Java

.NET C#

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.