Skip to main content
Version: 1.7.3

RequestByEmail

RequestByEmail

This is a payer-initiated method where the API sends a secure, personalized email to each recipient with a unique URL to complete their W-9 or W-8 form online. Each URL is scoped to that specific recipient and cannot be accessed by anyone else.

This is the most direct collection method when you have a known list of recipients and want to reach them through a familiar, professional channel.

When to use​

  • You have the complete list of recipients and their email addresses on file.
  • You want each recipient to receive a personalized invitation with their name and details pre-filled.
  • You prefer TaxBandits to handle email delivery rather than managing it through your own system.

If recipients are more likely to respond to an SMS, use RequestByText instead.

How it works​

  1. Authenticate

    Obtain a Bearer token via the OAuth 2.0 flow and include it in all request headers.

  2. Ensure a business (payer) exists

    Before calling this endpoint, confirm the payer has been created using the Business endpoint. If no BusinessId is provided in the request, the request will be associated with the default payer (the first payer created in your account).

  3. Call the endpoint

    Along with the payer and recipient details, your request may include the following optional parameters:

    • DBAId / DBARef — Scope the URL to a specific DBA under the payer. The DBA name will appear as the requester on the form.
    • Customization — Apply your logo and primary/secondary colors to brand the form page. Alternatively, pass a CustomizationId generated from the PortalCustomization endpoint.
    • EmailCustomization — Customizes the email sent to the recipient. You can apply your logo, primary/secondary colors, sender name, and sender email address to brand the email. Alternatively, pass an EmailCustomizationId generated from the EmailCustomization endpoint.
    • InterviewFlow — Set to TRUE to present the W-9 as a guided interview rather than a traditional form.
    • PrefLang — Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian, and Portuguese.
    • IsReminderEnabled — Set automated reminders to recipients who haven’t completed their forms.
    Automate TIN Matching

    Set IsTINMatching to TRUE to automatically trigger IRS TIN Matching once the recipient submits their form.

  4. Recipient completes the form

    TaxBandits sends the email to each recipient. When they open the link, they select the applicable form — W-9, W-8BEN, W-8BEN-E, W-8ECI, W-8IMY, or W-8EXP — and complete, e-sign, and submit it.

  5. Get notified

    Once a recipient submits, you can receive notification through any of the following:

    • Webhooks — Configure the 'WhCertificate Status Change' webhook event to receive a payload with the recipient's name, TIN, address, and a link to download the completed form. Learn more
    • Status endpoint — Poll the Status endpoint on demand to retrieve the current form status for a given recipient.
    • Web messaging — Receive in-browser notifications when a recipient completes their form. Learn more
POST WhCertificate/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestObjectSubmission-level settings for this request.
IsTINMatchingBooleanOptional Set to TRUE to automatically trigger IRS TIN Matching once the recipient submits their W-9.
IsReminderEnabledBooleanOptional Set to TRUE to send automatic reminder emails to recipients who have not yet completed their form.
RemainderSchdDaysNumberOptional Frequency (in days) at which reminder emails are sent. Requires IsReminderEnabled to be TRUE.
RequesterObjectIdentifies the payer associated with this request. If omitted, the default payer in your account is used.
PayerRefStringOptional Your unique identifier for the payer.
Size: 1-50
BusinessIdGuidOptional TaxBandits-generated unique identifier for the payer.
TINStringOptional Taxpayer Identification Number of the payer. Can be used in place of BusinessId or PayerRef.
Size: 9-11
Allowed values

"EIN", "SSN" (Including hyphen)

DBAIdStringOptional Unique identifier for the DBA. The DBA name appears as the requester on the form.
DBARefStringOptional Your reference identifier for the DBA.
Size: 1-50
RecipientsObject[]List of recipients to send the email request to. Each element represents one recipient.
PayeeRefStringOptional Your unique identifier for the recipient, used to reference them in future API calls.
Size: 1-50
NameStringOptional Recipient's name. Pre-filled on the form.
Size: 1-50
EmailStringEmail address of the recipient. The collection request email is sent to this address.
Size: 1-100
AddressObjectOptional Recipient's mailing address. Pre-filled on the form.
Address1StringOptional Street address or PO Box.
Size: 1-46
Address2StringOptional Suite or apartment number.
Size: 1-46
CityStringOptional City.
Size: 1-46
StateStringOptional Two-letter state code.
Size: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"

ZipCdStringOptional ZIP code. Format: 99999 or 99999-9999.
Size: 5-10
WebhookRefGuidOptional Unique identifier for a specific webhook callback URL configured in the Developer Console. If omitted, the response is posted to the default callback URL.
CustomizationIdGuidOptional A unique identifier for a saved customization profile, generated via the Developer Console or the PortalCustomization endpoint. Applies your branding to the form page.
EmailCustomizationIdGuidOptional Unique identifier for a saved email customization profile, generated via the Developer Console or the EmailCustomization endpoint. Applies your branding to the email.
CustomizationObjectOptional Inline branding settings for the form completion page. Use this if you do not have a CustomizationId.
BusinessLogoUrlStringOptional URL of the logo to display on the form page.
Size: 1-150
LogoPositionStringOptional Position of the logo on the form page.
Allowed values

"LEFT", "CENTER", "RIGHT"

InterviewFlowBooleanOptional Set to TRUE to present the W-9 as a guided step-by-step interview instead of the traditional form layout.
PrimaryColorStringOptional Primary brand color for the form page.
SecondaryColorStringOptional Secondary brand color for the form page.
PrefLangStringOptional Default display language for the form. Defaults to English if not set.
Allowed values

"en-US", "es-ES", "fr-FR", "de-DE", "uk-UA", "pt-PT"

Response Body

FieldTypeDescription
SubmissionIdGuidTaxBandits-generated unique identifier for this submission.
RequesterObjectPayer details associated with this request.
BusinessIdGuidTaxBandits-generated unique identifier for the payer.
BusinessNmStringPayer name. Returns the business name if the payer is an entity, or the full name if the payer is an individual.
FirstNmStringFirst name of the payer (individual).
Size: 1-20
MiddleNmStringMiddle name of the payer (individual).
Size: 1-20
LastNmStringLast name of the payer (individual).
Size: 1-20
SuffixStringSuffix of the payer (individual).
Allowed values

"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"

PayerRefStringYour unique identifier for the payer.
TINTypeStringTIN type of the payer.
TINStringTaxpayer Identification Number of the payer.
DBAIdStringUnique identifier for the DBA.
DBARefStringYour reference identifier for the DBA.
WhCertificateObjectResults of the W-9/W-8 collection requests submitted in this call.
SuccessRecordsObject[]Recipients for whom the request was successfully processed.
PayeeRefStringYour unique identifier for the recipient.
EmailStringEmail address to which the W-9/W-8 request was sent.
WhCertificateStatusStringCurrent status of the W-9/W-8 request.
StatusTsStringTimestamp of the last status update.
ErrorRecordsObject[]Recipients for whom the request failed.
PayeeRefStringYour unique identifier for the failed recipient.
EmailStringEmail address provided for the failed recipient.
ErrorsObject[]List of error details for this recipient.
IdStringTaxBandits-assigned error code.
NameStringField or node that triggered the error.
MessageStringHuman-readable error description.
ErrorsObject[]Top-level errors that prevented the entire submission from being processed. Null on success.
IdStringTaxBandits-assigned error code.
NameStringField or node that triggered the error.
MessageStringHuman-readable error description.

Request JSON​

Send email request and get notified via webhooks
Send a W-9/W-8 collection email to a recipient and link the completed form to a specific payer using BusinessId. When the recipient submits, the webhook is triggered automatically with the submitted form data.

{
  "SubmissionManifest": {
      "IsTINMatching": true,
      "IsReminderEnabled": true,
      "ReminderSchdDays": 10
  },
  "Requester": {
      "BusinessId": "959763e4-26d3-4d52-a8eb-b954b22616fd",
      "PayerRef": "Pay025",
      "TIN": "39-4589707",
      "DBAId": null,
      "DBARef": null
  },
  "Recipients": [
      {
          "PayeeRef": "payeeref016",
          "Name": "Shawn Williams",
          "Email": "shawn@sample.com",
          "Address": {
              "Address1": "1751 Kinsey Rd",
              "Address2": "Main St",
              "City": "Dothan",
              "State": "AL",
              "ZipCd": "36303"
          }
      }
  ],
  "WebhookRef": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D4",
  "CustomizationId": "D6ACC1C4-74E5-4A60-B569-77F4612BD988",
  "EmailCustomizationId": "2FF35B72-2EEF-466F-90EB-505FD250FD1L",
  "Customization": {
      "InterviewFlow": true,
      "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
      "LogoPosition": "CENTER",
      "PrimaryColor": "#1321E6",
      "SecondaryColor": "#0F700C",
      "PrefLang": "es-ES"
  }
}

Response JSON​

Success Response - This is a sample response for successful API requests.

{
  "SubmissionId": "2d1797a2-5e56-4da4-a59d-e82e858ffbd8",
  "Requester": {
      "BusinessId": "9e284b90-aa98-4287-8e9a-38cc590a90d3",
      "BusinessNm": "Snowdaze LLC",
      "PayerRef": "Pe12rtgr3",
      "TINType": "EIN",
      "TIN": "39-4589707",
  },
  "WhCertificate": {
      "SuccessRecords": [
          {
              "PayeeRef": "T@122",
              "Email": "mark@sample.com",
              "WhCertificateStatus": "ORDER_CREATED",
              "StatusTs": "2025-06-14 07:05:18 +05:30"
          },
          {
              "PayeeRef": "mia@345",
              "Email": "daniel@sample.com",
              "WhCertificateStatus": "ORDER_CREATED",
              "StatusTs": "2025-06-14 07:05:18 +05:30"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}