Skip to main content

Automating Form W-9 Using RequestByEmail (Payer-Initiated) Method - A Complete Workflow

· 6 min read
TaxBandits Tech

Form W-9 holds high significance among all the intricate facets of tax compliance, especially for businesses that deal with independent contractors.

TaxBandits API offers a seamless solution to automate the W-9 collection process right from your software or portal. By integrating TaxBandits API, you can automate the W-9 process in two different ways – RequestByURL (Payee-initiated) and RequestByEmail (Payer-Initiated).

In our previous blog, we discussed how to automate W-9 using In this blog, we’ll guide you on how to automate Form W-9 using the RequestByUrl (Payee-Initiated) method. Here, we’ll discuss how the RequestByEmail Method works.

1. Preliminary Steps

Before initiating the W-9 automation, you must complete a few preliminary procedures.

  • Webhook Configuration - As you may know, TaxBandits API employs webhooks to provide you with status updates regarding your filings. You can enable webhook notifications for different types of events. To receive updates related to W-9, you must configure the ‘Form W-9 Status Change’ webhook. This webhook payload will also contain the TIN matching status if it is opted as part of a W-9 request. If you prefer to opt for TIN Matching separately, then you must configure the ‘TIN Matching Status Change’ webhook as well.

  • OAuth 2.0 Authentication - This is a common step for every endpoint. Before using any endpoint, you must get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. For detailed information, click here.

Header:-

{
"alg": "HS256", /*Algorithm = HS256*/
"typ": "JWT" /*Type = JSON Web Token (JWT)*/
}

Payload:-

{
"iss": "968a9c78dae29a29",  /*Issuer: Client ID retrieved from the console site*/
"sub": "968a9c78dae29a29",  /*Subject: Client ID retrieved from the console site*/
"aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token retrieved from the console site*/
"iat": 1516239022 /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
}

Signature:-

  HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg  /*Client Secret retrieved from the console site*/
)

Sample JWS:-

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

OAuth server will receive the JWS & will validate to provide the JWT (Access token) in the following response format:

{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3Rlc3RvYXV0aC5leHByZXNzYXV0aC5uZXQvdjIvIiwic3ViIjoiOWYzZTQwM2RlMWQ5YTNkMiIsImF1ZCI6ImNhNjRkNzMyMzBhNDRkMjY4MjkzN2I2ODQ0ZmJjNTI4IiwiaWF0IjoxNjk0NTg1NDU4LCJleHAiOjE2OTQ1ODkwNTh9.WPOCs-lxo3GXz7_zGGmQovWZy4WD0smW7n-U-InuoXE",
"TokenType": "Bearer",
"ExpiresIn": 3600,
"Errors": null
}
  • Business Creation - Using the Business/Create endpoint, you can create the business for which you need to collect W-9.

Request:

{
   "BusinessNm": "Snowdaze LLC",
   "PayerRef": "Snow123",
   "TradeNm": "Iceberg Icecreams",
   "IsEIN": true,
   "EINorSSN": "003313330",
   "Email": "james@sample.com",
   "ContactNm": "John",
   "Phone": "1234567890",
   "PhoneExtn": "12345",
   "Fax": "1234567890",
   "BusinessType": "ESTE",
   "SigningAuthority": {
       "Name": "James Smith",
       "Phone": "1234567890",
       "BusinessMemberType": "ADMINISTRATOR"
   },
   "KindOfEmployer": "FEDERALGOVT",
   "KindOfPayer": "REGULAR941",
   "IsBusinessTerminated": false,
   "IsForeign": true,
   "USAddress": {
       "Address1": null,
       "Address2": null,
       "City": null,
       "State": null,
       "ZipCd": null
   },
   "ForeignAddress": {
       "Address1": "22 St",
       "Address2": "Clair Ave E",
       "City": "Toronto",
       "ProvinceOrStateNm": "Ontario",
       "Country": "CA",
       "PostalCd": "M1R 0E9"
   }
}

Response:

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "BusinessId": "bfe7ee55-835c-4fe1-a2b7-1e7c3027598b",
    "PayerRef": "Snow123",
    "IsEIN": true,
    "EINorSSN": "XX-XXX3330",
    "BusinessNm": "Snowdaze LLC",
    "Errors": null
}

2. Using RequestByEmail Endpoint

Once the OAuth 2.0 process is complete, you can use [POST] FormW9/RequestByEmail endpoint. You can include the following parameters in your API request.

  • Access Token - As described earlier, you must include the JWT you obtained through the OAuth 2.0 process in the header of any API request.

  • Payee Email Address - Provide the email address of the recipient (payee) to which they will receive the link to complete their W-9 form.

  • Payee Reference (PayeeRef) - This can be a vendor ID, contractor number, or any other value that uniquely identifies the corresponding recipient (payee).

  • Payee Name and Address (Optional) - Your request may also include the payee’s name and address.

  • Business Identifier - When you created the business earlier, TaxBandits would have generated a Business ID in the response. You can either provide that or TIN in this request. If you fail to provide the business ID in this request, the W-9 collected from the payee will be stored under the default business, i.e., the first business added to your account.

  • DBA Reference (Optional) - If the business has multiple DBA names, you can mention the DBA name you want to use as the Requester Name on W-9 Forms.

In addition to these, you can opt for TIN Matching in the same API request. All you need to do is set the ‘IsTINMatching’ to True.

3. Customization Options

TaxBandits API provides you with a wide range of options to showcase your brand identity wherever applicable.

Here, when requesting a W-9 using the RequestByEmail method, you will have the option to customize the email and the Secure URL (W-9 completion page) with your business logo. To do so, you must include the logo in the BusinessLogoUrl field in your API request.

Here is a sample request and response of the RequestByEmail method:

Request :

{
 "SubmissionManifest": {
   "IsTINMatching": true
 },
 "Requester": {
   "BusinessId": "cb52b7cc-ad50-4008-a6fd-8382f45adb4a",
   "PayerRef": null,
   "TIN": null
 },
 "Recipients": [
   {
     "PayeeRef": "894654",
     "Name": “Shawn”,
     "Email": "shawn@sample.com",
     "Address": {
       "Address1": "71 st nicholas drive",
       "Address2": null,
       "City": "Northpole",
       "State": "AK",
       "ZipCd": "99705"
    }
   }
 ],
 "Customization": {
    "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png"
  }
}

Response :

{
    "SubmissionId": "31c2d072-016a-4378-af10-0476c54f1229",
    "Requester": {
        "BusinessId": "b7a03275-bb2a-4eb4-a745-65a1f50c9b5c",
        "PayerRef": "E3722",
        "BusinessNm": "Snowdaze LLC",
        "TINType": "EIN",
        "TIN": "20-1652593",
        "DBAId": null,
        "DBARef": null
    },
    "FormW9Records": {
        "SuccessRecords": [
            {
                "PayeeRef": "894654",
                "Email": "shawn@sample.com",
                "W9Status": "ORDER_CREATED",
                "StatusTs": "2024-06-26 05:44:00 -04:00"
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}

4. W-9 Completion and TIN Matching

Upon your request, the API will trigger emails to the respective recipients. The recipients can complete and submit their W-9 forms using the secure URL provided in the email.

Once they complete, the TIN Matching will begin, and you’ll receive a webhook notification (if configured as described in preliminary steps) regarding completion. The notification will also include a link to access the completed W-9. You can also use the Status endpoint to retrieve the status.

Webhook Sample:

{
  "SubmissionId": "ad754d66-021d-4c9f-998b-180fda6dbea1",
  "Requester": {
    "BusinessId": "b7a03275-bb2a-4eb4-a745-65a1f50c9b5c",
    "PayerRef": "E3722",
    "BusinessNm": "Snowdaze LLC",
    "TINType": "EIN",
    "TIN": "XX-XXX2593",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "894654",
  "RecipientId": "29e7d179-4931-4612-9048-ff1df83bba02",
  "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
  "StatusTs": "2024-06-26 05:54:14 -04:00",
  "TINMatching": {
    "Status": "ORDER_CREATED",
    "StatusTs": "2024-06-26 05:54:15 -04:00",
    "StatusMsg": null,
    "Errors": null
  },
  "FormW9RequestType": "Email_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/6c0ae2de-17a2-441d-b247-c7d52cfc8052.Pdf",
  "Email": "shawn@sample.com",
  "FormData": {
    "Line1Nm": "Shawn",
    "Line2Nm": "Iceberg Icecreams",
    "TINType": "EIN",
    "TIN": "XX-XXX7846",
    "Address": {
      "Address1": "71 SAINT NICHOLAS DR",
      "Address2": null,
      "City": "NORTH POLE",
      "State": "AK",
      "ZipCd": "99705-7752"
    },
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false
  },
  "Errors": null
}

If you have opted for TIN Matching, you’ll receive that status in the subsequent webhook notifications. If TIN Matching fails, you may have to request a new W-9 from the payee again.

This is how you can automate the W-9 process using the RequestByUrl method. You can use the same procedure to automate Form W-8BEN using the FormW8Ben/RequestByEmail endpoint. If you want the recipients to choose and fill either W-9, W-8BEN, or W-8BEN-E based on their citizenship status, you can use the WhCertificate/RequestByEmail endpoint.

For more detailed information, you can refer to our comprehensive documentation.