Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.7.1

Get

This method will return the completed W-9 of a particular recipient. The response will have the W-9 information such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9.

Key Points

  • Only W-9s with the ‘completed’ and ‘completed and TIN matching Inprogress’ status can be retrieved using the Get method. If the status of the W-9 is other than ‘completed’ and ‘completed and TIN matching Inprogress’, it will not be returned.
  • If you do not supply the BusinessId in the request, then the W-9 that matches the Email or PayeeRef linked to the default business will be retrieved.
  • If there are multiple W-9s for the same Email or PayeeRef, the last completed W-9 will be retrieved.
GET FormW9/Get

Request Body

FieldTypeDescription
PayeeRefStringUnique identifier of a recipient. Either PayeeRef or Email is required
Size Range: 1-50
EmailStringEmail Address of the recipient.
Size Range: 1-50
BusinessIdGuidOptional Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TINStringOptional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN
Size Range: 9-11

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
RequesterObjectRequester information.
    BusinessIdGuidA unique identifier of the business.
    BusinessNmStringRequester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINTypeStringTIN Type of the Requester.
    TINStringTaxpayer Identification Number of the requester.
PayeeRefStringUnique identifier of the recipient
RecipientIdGuidAn unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to update.
W9StatusStringStatus of the W-9
StatusTsStringTimestamp of the W-9 Status
TINMatchingObjectTIN Matching information.
    StatusStringTIN Matching status.
    StatusTsStringTimestamp of the TIN Matching Status.
    ErrorsStringShows the detailed error message.
FormW9RequestTypeStringForm W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API method RequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
PdfUrlStringURL to download the completed W-9
EmailStringEmail Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the API method RequestByURL
FormDataObjectForm W-9 data of the recipient
    Line1NmstringName as shown on the income tax return
    Line2NmstringBusiness name/disregarded entity name, if different from Line1 Name
    TINTypestringTIN type of the recipient. Either EIN or SSN
    TINstringRecipient’s TIN
    AddressObjectRecipient’s complete address
        Address1stringRecipient’s Address 1 (number, street)
        Address2stringRecipient’s Address 2 (apt. or suite no.)
        CitystringRecipient’s City
        StatestringRecipient’s State
        ZipCdstringRecipient’s Zip Code
    FederalTaxClassificationstringU.S. Federal Tax Classification of the person whose name is entered on Line 1
    ExemptPayeeCdstringThis code identifies the recipient is exempt from backup withholding
    ExemptFromFATCAstringThis code identifies recipients that are exempt from reporting under FATCA.

Request 1: Get W-9 data of a recipient with PayeeRef and BusinessId

FormW9/Get?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Response 1: The response will have the completed W-9N information for the given Payee Reference corresponding to the BusinessId. In addition, the Response Payload will also have the PdfUrl link to download the W-9.

{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "steve@abcinc.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}

Request 2: Get W-9 data of a recipient with Email and BusinessId.

FormW9/Get?Email=steve@abcinc.com&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Response 2: The response will have the completed W-9 information for the given Email corresponding to the BusinessId. In addition, the Response Payload will also have the PdfUrl link to download the W-9.

{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": null,
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "steve@abcinc.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}

Request 3: Get W-9 data of a recipient with PayeeRef and TIN.

FormW9/Get?PayeeRef=Pe123451234&TIN=22-2222222

Response 3: The response will have the completed W-9 information for the given PayeeRef corresponding to the TIN. In addition, the Response Payload will also have the PdfUrl link to download the W-9.

{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "steve@abcinc.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}

Request 4: Get W-9 data of a recipient with PayeeRef.

FormW9/Get?PayeeRef=Pe123451234

Response 4: Completed Form W-9 information corresponding to the default business will be retrieved for the given PayeeRef. In addition, the Response Payload will also have the PdfUrl link to download the W-9.

{
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"PayeeRef": "Pe123451234",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": null
},
"FormW9RequestType": "URL_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "steve@abcinc.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "11-1111111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "E"
},
"Errors": null
}

Request 5: Get W-9 data of a recipient with PayeeRef [Which is not completed].

FormW9/Get?PayeeRef=Pe123451234

Response 5: No completed W-9s are found for the given PayeeRef. Therefore, a corresponding error message will be displayed.

{
"SubmissionId": "00000000-0000-0000-0000-000000000000",
"Requester": null,
"PayeeRef": null,
"W9Status": null,
"StatusTs": null,
"TINMatching": null,
"FormW9RequestType": null,
"PdfUrl": null,
"Email": null,
"FormData": null,
"Errors": [
{
"Id": "F08-100014",
"Name": "No Records",
"Message": "No completed W-9s were found for the given Request"
}
]
}