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 or W-8BEN of a particular recipient. The response will have the information such as the Name, Address, Country of citizenship and TIN number along with the link to download the completed Form W-9 or W-8BEN.

Key Points

  • Only W-9s or W-8BENs with the completed status can be retrieved using the Get method. If the status of the form is other than complete, it will not be returned.
  • If you do not supply the BusinessId or TIN or PayerRef in the request, then the W-9 or W-8BEN that matches the PayeeRef linked to the default business will be retrieved.
  • If there are multiple forms for the same PayeeRef, the last completed form will be retrieved.
GET WhCertificate/Get

Request Body

FieldTypeDescription
PayeeRefStringA unique identifier for each recipient completing the Form W-9 and W-8BEN. This identifier will be used in future references of the recipient in the API.
Size Range: 1-50
BusinessIdGuidOptional TaxBandits Unique Business Identifier. This ID is generated by `TaxBandits after you create a business in your account using the Business endpoint.If you do not supply the BusinessId in the request, then the W-9 or W-8BEN that matches the PayeeRef linked to the default business will be retrieved. (First business created in your account).
TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId.
Size Range: 9-11
Allowed values: "EIN", "SSN" (Including hyphen)
PayerRefStringOptional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50

Response Body

FieldTypeDescription
FormTypeStringType of Form (W-9 or W-8BEN).
FormW9ObjectContains Form W-9 Information.
    SubmissionIdGuidUnique identifier of a submission.
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the business.
        PayerRefStringAn unique identifier of the business. Assigned by the client.
        BusinessNmStringBusiness Name of the requester. 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 W-9 is completed. Clients can use this ID to file Form 1099s for this recipient.
    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.
COMMON_URL_API - Form W-9 was requested using the API method RequestByUrl.
    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.
ErrorsObjectShows detailed error information.
        IsBackUpWHBooleanWhen true, identifies the recipient is subject to backup withholding. The completed Form W-9 PDF will have the item 2 under Part II crossed out. When false, identifies the recipient is not subject to backup withholding.
FormW8BenObjectForm W-8BEN Information.
    SubmissionIdGuidUnique identifier of a submission.
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the business.
        PayerRefStringAn unique identifier of the business. Assigned by the client.
        BusinessNmStringBusiness Name of the requester. 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
    W8BENStatusStringStatus of the W-8BEN.
    StatusTsStringTimestamp of the W-8BEN Status.
    FormW8BENRequestTypeStringForm W-8BEN requested Type.
COMMON_URL_API - Form W-8BEN was requested using the API method RequestByUrl.
    PdfUrlStringURL to download the completed W-8BEN.
    EmailStringEmail Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL.
    FormDataObjectForm W-8BEN data of the recipient.
        NmOfIndividualstringName of the Foreign Individual.
        CitizenOfCountrystringRecipient country of citizenship.
        USTINTypestringTIN type of the recipient. Either SSN or ITIN.
        USTINstringRecipient’s TIN
        ForeignTINstringForeign TIN of the recipient.
      IsFTINNotLegallyRequiredBooleanWhen TRUE, Identifies that benificial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence.
        DOBstringDate of Birth of the recipient
        PermanentAddressObjectRecipient’s permanent address.
            AddressstringRecipient’s Address.
            CitystringRecipient’s City
            StatestringRecipient’s State
            CountrystringRecipient’s Country
            PostalCdstringRecipient’s Zip Code
        MailingAddressObjectRecipient’s mailing address.
            AddressstringRecipient’s Address.
            CitystringRecipient’s City
            StatestringRecipient’s State
            CountrystringRecipient’s Country
            PostalCdstringRecipient’s Zip Code
        TaxTreatyBenefitsObjectTax Treaty Benefits.
            BeneficiaryCountrystringCountry where the recipient claim to be a resident for income tax treaty purposes.
            ClaimingProvArticleParastringArticle and paragraph of the treaty benefits.
            RateOfWHstringRate of Withholding.
            TypeOfIncomestringType of income for which recipient claiming the treaty benefits.
            AdditionalConditionsstringAdditional conditions from the tax treaty benefits.
        SignatureObjectSignature of the recipient.
            SignerNmstringName of the signer.
    ErrorsObjectShows detailed error information.

Get Request 1: Get form details with just Recipient Payee Reference. "PayeeRef linked to the default business will be retrieved. First business created will always be a default business."

WhCertificate/Get?PayeeRef=Pe123451234

Get Request 2 : Get form details with Recipient Payee Reference and BusinessID.

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

Get Request 3 : Get form details with Recipient Payee Reference and Business TIN.

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

Get Request 4: Get form details with Recipient Payee Reference and Payer Reference.

WhCertificate/Get?PayeeRef=Pe123451234&PayerRef=Me1231231233

Response for W8-BEN: A response will have information such as the Name, Address, Country of citizenship, along with the link to download the completed W-8BEN.

{ "FormType": "W8Ben", "FormW9": null, "FormW8Ben": {   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",   "Requester": {     "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",     "PayerRef": null,     "BusinessNm": "John Enterprises",     "TINType": "EIN",     "TIN": "22-2222222"   },   "PayeeRef": "7484391234545",   "W8BENStatus": "COMPLETED",   "StatusTs": "2021-02-19 14:36:28 -05:00",   "FormW8BENRequestType": "URL_API",   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",   "Email": "steve@abcinc.com",   "FormData": {     "NmOfIndividual": "Joseph Smith",     "CitizenOfCountry": "Canada",     "USTINType": "SSN",     "USTIN": "111-11-1111",     "ForeignTIN": null,     "IsFTINNotLegallyRequired": true,     "DOB": "07/08/1990",     "PermanentAddress": {       "Address": "123 E. Main St",       "City": "Rock Hill",       "State": "SC",       "Country": "USA",       "ZipCd": "29730"     },     "MailingAddress": {       "Address": null,       "City": null,       "State": null,       "Country": null,       "ZipCd": null     },     "TaxTreatyBenefits": {       "BeneficiaryCountry": "Canada",       "ClaimingProvArticlePara": "VII",       "RateOfWH": "27.50",       "TypeOfIncome": "Royalties",       "AdditionalConditions": null     },     "Signature": {       "SignerNm": "Joseph"     }   },   "Errors": null }, "Errors": null}

Response for FormW9: If the form type is W-9, the TIN matching is a part of the response, along with the link to download the completed W-8BEN.

{ "FormType": "FormW9", "FormW9": {   "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",   "Requester": {     "BusinessId": "fb6ddd28-ad30-4fc2-bd17-38a937f2aa81",     "BusinessNm": "John Enterprises",     "PayerRef": null,     "TINType": "EIN",     "TIN": "XX-XXX2222"   },   "PayeeRef": "Pe123451234",   "RecipientId": "sdf3ccee-10d8-4eb4-ab81-234234c9636",   "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",   "StatusTs": "2021-06-24 10:40:21 -04:00",   "TINMatching": {     "Status": "ORDER_CREATED",     "StatusTs": "2021-06-24 10:40:21 -04:00",     "StatusMsg": null,     "Errors": null   },   "FormW9RequestType": "Email_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": "XX-XXX1111",     "Address": {       "Address1": "123 E. Main St",       "Address2": "Suite 400",       "City": "Rock Hill",       "State": "SC",       "ZipCd": "29730"     },     "FederalTaxClassification": "C Corporation",     "ExemptPayeeCd": "5",     "ExemptFromFATCA": "F",     "IsBackUpWH": false   },   "Errors": null }, "FormW8Ben": null, "Errors": null}