Skip to main content
Version: 1.7.1

Get

Get

Use this endpoint to retrieve the completed W-9/W-8 for a specific recipient (payee). The response will include key details such as the payee's name, address, country of citizenship, TIN, and a secure download link for the completed form.

Key Points​

  • Only completed forms can be retrieved using this endpoint. If the form status is anything other than "Completed," no data will be returned.
  • If you do not provide a BusinessId, TIN, or PayerRef, the API will return the W-9/W-8 form associated with the matching PayeeRef under your default business.
  • If multiple completed forms exist for the same PayeeRef, the API will return the most recently completed form.
GET WhCertificate/Get
Run in Postman

Request Params

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 A unique business identifier generated by TaxBandits after you create a business in your account using the Business endpoint. If you do not provide the BusinessId in the request, then the W-9 or W-8BEN that matches the PayeeRef linked to the default business, i.e., the first business created in your account, will be retrieved.
TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId.
Size Range: 9-11.
PayerRefStringOptional A unique payer identifier that you will assign while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
EmailStringThe email address of the recipient
Size Range: 1-100

Response Body

FieldTypeDescription
FormTypeStringType of Form (W-9 or W-8BEN).
FormW9ObjectContains Form W-9 Information.
    SubmissionIdGuidA unique identifier of a submission
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the business.
        PayerRefStringA 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.
    PayeeRefStringA unique identifier of the recipient
    RecipientIdGuidA unique ID generated by TaxBandits after the W-9 is completed. You 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.
        ErrorsObject[]Shows the detailed error message.
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows the error message.
    FormW9RequestTypeStringForm W-9 requested Type.
COMMON_URL_API - Form W-9 was requested using the RequestByUrl method.
    PdfUrlStringThe URL provided to download the completed W-9.
Note: This URL will expire in 24 hours.
    EmailStringThe email 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 RequestByURL method.
    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 (street address or post office box of that locality). This will be pre-filled on the Form.
        Address2stringRecipient’s Address 2 (suite or apartment number). This will be pre-filled on the Form.
            CitystringRecipient’s City
            StatestringRecipient’s State
            ZipCdstringRecipient’s Zip Code
Size Range: 5..10
        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.
ErrorsObject[]Shows detailed error information.
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows the error message.
        IsBackUpWHBoolean
  • When 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.
    SubmissionIdGuidA unique identifier of a submission.
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the business.
        PayerRefStringA unique payer identifier that you will assign
        BusinessNmStringThe Business 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.
    PayeeRefStringA unique identifier of the recipient
    W8BENStatusStringStatus of the W-8BEN.
    StatusTsStringTimestamp of the W-8BEN Status.
    FormW8BENRequestTypeStringForm W-8BEN requested Type.
  • URL_API - Form W-8BEN was requested using the RequestByURL method.
  • Email_API - Form W-8BEN was requested using the RequestByEmail method.
  • Email_UI - Form W-8BEN was requested from the TaxBandits UI application.
    PdfUrlStringThe URL to download the completed W-8BEN.
Note: This URL will expire in 24 hours.
    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 RequestByURL method.
    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 beneficial 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 claims the treaty benefits.
            AdditionalConditionsstringAdditional conditions from the tax treaty benefits.
        SignatureObjectSignature of the recipient.
            SignerNmstringName of the signer.
    ErrorsObject[]Shows detailed error information.
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows the error message.

Request Params​

Get the form details using just Recipient Payee Reference. "PayeeRef linked to the default business, i.e., the first business created, will be retrieved.

WhCertificate/Get?PayeeRef=payeeref1

Response JSON​

The 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": "Snowdaze LLC",
        "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": "sample@bodeem.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
   }