Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.6.1

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

FieldTypeDescription
RecordIdGuidOptional Specify the RecordId of the return
TINMaskTypestringOptional TIN Mask type on the TIN printed on the PDF
Allowed values: "MASKED", "UNMASKED"
TaxYearstringOptional Tax Year of the return. Specify only if you do not have the RecordId
BusinessobjectOptional Collects the Business identifier TIN or TBS Business Id or PayerRef. This object information is required only if you do not have the RecordId
    BusinessIdGuidOptional TaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
    PayerRefstringOptional Unique payer identifier assigned by the client.
Size Range: 1 to 50
    EINstringOptional Employer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9 to 10
EmployeeobjectOptional Collects the employee's unique identifier. This object information is required only if you do not have the RecordId
    EmployeeIdGuidOptional Unique Employee Identifier generated by TaxBandits
    SSNstringOptional Social Security Number. Use this as an alternative for EmployeeIds.
Size Range: 9 to 11

Response Body

FieldTypeDescription
RecordIdGuidUnique identifier of the record
EmployeeIdGuidUnique Employee Identifier generated by TaxBandits
DraftPdfUrlstringURL of the Draft PDF
Errorsobject[]Shows detailed error information
    IdstringReturns the validation error code
    NamestringName of the validation error
    MessagestringDescription of the validation error

Request JSON 1: With just the RecordId

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

Response JSON 1

{   "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",   "EmployeeId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",   "DraftPdfUrl": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/W-2/221556/dcopy_tbs_wm_1up_221556.pdf",   "Error": null}

Request JSON 2: With No RecordId

{ "TaxYear": "2021", "RecordId": null, "TINMaskType":"Unmasked", "Business": {   "BusinessId": "94B6214D-8DCA-490C-8FC3-602840B439B5",   "PayerRef": null,   "EIN": null }, "Employee": {   "EmployeeId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",   "SSN": null }}

Response JSON 2

{   "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",   "EmployeeId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",   "DraftPdfUrl": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/W-2/221556/d/copy_tbs_wm_1up_221556.pdf",   "Error": null}