Guides

Collecting Tax Documentation

Suggest Edits

🚧

This page is marked as deprecated, but Taxbit will continue supporting customers currently using these solutions. If you’d like to learn more about upgrading to our new React SDK with enhanced Digital W8/W9 support, reach out to our team today.

You can use the tax form we provide in the TaxBit SDK to collect tax documentation from your customers. We will securely store this tax information on our servers and use it to generate the necessary documents for tax compliance.

You can load the collection form using the code sample below.

Loading the tax documentation form

taxBit.ui.taxDocumentation.collect({  
  hostElement: document.querySelector("#tax-info-container")
});

This code will create an iframe and append it to the DOM element you specified in the hostElement option. The host element must be able to contain nested elements. Typically, customers use a <div></div> block as the host element. Regardless of your HTML, we recommend giving your container element an attribute ID, like <div id="taxbit-container"></div>, making it easier to customize later.

The iframe will then display a form to collect tax documentation. We host this form on a TaxBit content delivery network (CDN). The iframe will use the entire width of the <div id="taxbit-container"></div> block and will automatically resize its height to match the content inside the iframe.

If you'd like to restrain the height of the tax collection form, You can use CSS to set the height of the <div id="taxbit-container"></div> block. You will also want to enable vertical scrolling. For example, <div id="taxbit-container" style="height: 3rem; overflow-y: scroll;"></div>. Otherwise, people may only see the top part of your form. See the documentation for overflow-y for more information.

Receiving notification of critical events

The collect function will return a promise, which the system will resolve once the collection form is fully loaded. We use an object to resolve this promise, which contains another promise that we resolve once the user completes the tax documentation form successfully.

After the form is submitted successfully, a link to download the PDF file is displayed for the end user.

Receiving notification of events

const collectResult = await taxBit.ui.taxDocumentation.collect({  
  hostElement: document.querySelector("#tax-info-container")
});

// At this point, the form has been loaded in the iframe.

await collectResult.formCompletion;

// At this point, the user has successfully completed the tax documentation form.

After successfully submitting Tax Documentation

Confirmation is shown and the user is given access to the PDF of the W-9, W-8BEN, or W-8BEN-E.

Handling errors

If errors occur while the form loads or while the user completes the form, the system will reject the promise. The SDK will do its best to display a friendly error message to the user.

You should also handle these errors and provide a graceful user experience tailored to your application. For example, you could navigate the user to another part of your program.

let collectResult;

try {
  collectResult = await taxBit.ui.taxDocumentation.collect({  
    hostElement: document.querySelector("#tax-info-container")
  });
} catch (error) {
  // Handle the error that occurred while loading the form.
}

try {
  await collectResult.formCompletion;
} catch (error) {
  // Handle the error that occurred while the user was completing the form.
}

Specifying a document type

By default, the collection form will ask your customer for information to determine whether they need a W-8BEN, W-8BEN-E, or W-9 tax form. However, if you know which document the customer qualifies for, you can pass that information into the form when you create it using the documentType key. Setting documentType will prevent the form from generating tax-form-related fields.

taxBit.ui.taxDocumentation.collect({  
  hostElement: document.querySelector("#tax-info-container"),
});

Supported document types

  • W-9
  • W-8BEN
  • W-8BEN-E

If you are unsure whether the user will need a W-8BEN, W-8BEN-E, or W-9, leave the documentType blank. The SDK will ask questions to determine the appropriate document type for the account.

Providing pre-collected data

Your system likely already has some basic information about your customer, like a name and address. By providing this data to the SDK, the SDK can auto-populate related form fields or skip questions altogether, resulting in a more streamlined experience for your customer. You can use this functionality by providing a data object that includes your existing data.

taxBit.ui.taxDocumentation.collect({  
  hostElement: document.querySelector("#tax-info-container"),
  data: {
    documentType: "W-9"
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      secondLine: "Apt 204",
      city: "Seattle",
      stateOrProvince: "WA",
      postalCode: "98101",
      country: "US",
    },
    taxClassification: "INDIVIDUAL"
  }
});

The pieces of data you are allowed to provide depend on the value you have specified for documentType. If documentType is left blank, you may provide data in any W-8BEN, W-8BEN-E, and W-9 forms.

Note: The SDK intentionally provides leniency for provided values. For example, if you pass an invalid value of foo for taxClassification, the SDK will discard the value rather than throw an error. The collection form will then ask your customer any questions necessary to arrive at accurate and complete data. Rules for when field values will be discarded are detailed below.

Undetermined documentType

We support all fields found in the W-8BEN, W-8BEN-E, or W-9. The SDK will do its best to fill in the fields when possible, leading the user to a completed form.

name: string (optional)

For individuals, the value of this key is the first and last name of the account owner, not the name of their company—for example, Phil Myman.

For businesses, this is the name of the business that owns the account. For example, Company ABC Inc.

The system will discard this value if you set the taxClassification field to SMLLC.

address.firstLine: string (optional)

The value of this key is the first line of the customer's address.

The system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.secondLine: string (optional)

The value of this key is the second line of the customer's address.

This system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.city: string (optional)

The value of this key is the customer's city.

The system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions is true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

address.postalCode: string (optional)

The value of this key is the postal code of the customer's address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

address.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's country.

The system will discard this field if any of the following conditions are true:

Note: If you don't provide a value for this field, the system will try to derive the country code using address.stateOrProvince.

tin: string (optional)

The value of this key is the customer's Taxpayer Identification Number (TIN).

The Taxpayer ID Number (TIN) can be in one of the following formats:

  • NN-NNNNNNN
  • NN-NNN-NNNN
  • NNNNNNNNN

The system will discard this field if any of the following conditions are true:

  • The value is not a nine-digit string.
  • The tinType field is empty.
  • You've set the taxClassification field to SMLLC.

tinType: string (optional)

The value of this key is the customer's TIN type.

Supported values:

  • SSN
  • EIN

The system will discard this field if any of the following conditions are true:

  • The value is not supported.
  • You have already entered a valid value in the taxClassification field. In this case, the system will automatically set the value of tinType to the appropriate Tax ID type.
  • You've set the taxClassification field to SMLLC.

taxClassification: string (optional)

The value of this key is the tax classification of the customer.

The supported values are:

  • INDIVIDUAL
  • SOLE_PROPRIETOR
  • SMLLC
  • C_CORPORATION
  • S_CORPORATION
  • PARTNERSHIP
  • TRUST_ESTATE
  • LLC_C
  • LLC_S
  • LLC_P
  • OTHER
  • CORPORATION
  • SIMPLE_TRUST
  • COMPLEX_TRUST
  • GRANTOR_TRUST
  • ESTATE
  • CENTRAL_BANK_OF_ISSUE
  • FOREIGN_GOVERNMENT_CONTROLLED_ENTITY
  • FOREIGN_GOVERNMENT_INTEGRAL_PART
  • TAX_EXEMPT_ORGANIZATION
  • PRIVATE_FOUNDATION
  • INTERNATIONAL_ORGANIZATION
  • DISREGARDED_ENTITY

The system will discard this field if its value isn't one of the enumerated values above.

referenceNumbers: string (optional)

The legal name of the account's beneficial owner or the US or foreign Disregarded Entity (DRE) owner.

country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's country of citizenship or country of incorporation or organization.

The system will discard this field if any of the following conditions are true:

permanentAddress.firstLine: string (optional)

The value of this key is the first line of the customer's permanent residence address.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.secondLine: string (optional)

The value of this key is the second line of the customer's permanent residence address.

This system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.city: string (optional)

The value of this key is the customer's permanent residence city.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

permanentAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's permanent residence address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

permanentAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince.

mailingAddress.firstLine: string (optional)

The value of this key is the first line of the customer's mailing address.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.secondLine: string (optional)

The value of this key is the second line of the customer's mailing address.

This system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.city: string (optional)

The value of this key is the customer's mailing city.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

mailingAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's mailing address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

mailingAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince.

dateOfBirth: string (optional)

For individuals, this key's value is the account owner's date of birth. It must be entered in the format MM/DD/YYYY.

The system will discard this field if any of the following conditions are true:

  • If the provided string is not a valid date in this format.
  • You've set the taxClassification field to SMLLC.

ftin: string (optional)

The value of this key is the customer's foreign tax identification number (FTIN). There are no validations on foreign tax identification numbers.

It will be discarded if the taxClassification is set to SMLLC.

ftinNotLegallyRequired: boolean (optional)

The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.

dbaName: string (optional)

The value of this field is the Doing Business As (DBA) name, trade name, or the disregarded entity name of the account owner. It is different from the name property listed above. For example, the name field might be Pat Smith, whereas dbaName might be Pat's Plumbing LLC.

exemptPayeeCode: string (optional)

The exempt payee code applies to specific types of businesses and government entities generally exempt from backup withholding and information reporting requirements. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values from 1 to 13, with each number representing a qualifying entity type. For example, payee code 7 means a futures commission merchant registered with the Commodity Futures Trading Commission. You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

  • The value is not a string representation of any number between 1 and 13.
  • You've set the taxClassification field to SMLLC.

exemptionFatcaCode:string (optional)

The Foreign Account Tax Compliance Act (FATCA) reporting exempt code is similar to the exempt payee code but relates to those businesses and government entities exempt from FATCA reporting. FATCA is a global tax regime directed at U.S. tax residents who maintain accounts with foreign financial institutions. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values of A to M, with each letter representing a qualifying entity type. For example, FATCA exempt code D means a corporation whose stock is regularly traded on one or more established securities markets as described in Regulations section 1.1472-1(c)(1)(i). You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

  • The value is not a character between A and M.
  • You've set the taxClassification field to SMLLC.

otherTaxClassification: string (optional)

If the customer falls into another tax classification, provide the tax classification of that entity. Any string is acceptable.

W-9 documentType

The following are W-9 properties.

dbaName: string (optional)

The value of this field is the Doing Business As (DBA) name, trade name, or the disregarded entity name of the account owner. It is different from the name property listed above. For example, the name field might be Pat Smith, whereas dbaName might be Pat's Plumbing LLC.

taxClassification: string (optional)

The value of this key is the tax classification of the customer.

The supported values are:

  • INDIVIDUAL
  • SOLE_PROPRIETOR
  • SMLLC
  • C_CORPORATION
  • S_CORPORATION
  • PARTNERSHIP
  • TRUST_ESTATE
  • LLC_C
  • LLC_S
  • LLC_P
  • OTHER
  • DISREGARDED_ENTITY

The system will discard this field if its value isn't one of the enumerated values above.

otherTaxClassification: string (optional)

If the customer falls into another tax classification, provide the tax classification of that entity. Any string is acceptable.

The system will discard this field unless you set the taxClassification field to OTHER.

exemptPayeeCode: string (optional)

The exempt payee code applies to specific types of businesses and government entities generally exempt from backup withholding and information reporting requirements. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values from 1 to 13, with each number representing a qualifying entity type. For example, payee code 7 means a futures commission merchant registered with the Commodity Futures Trading Commission. You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

  • The value is not a string representation of any number between 1 and 13.
  • You've set the taxClassification field to SMLLC.

exemptionFatcaCode:string (optional)

The Foreign Account Tax Compliance Act (FATCA) reporting exempt code is similar to the exempt payee code but relates to those businesses and government entities exempt from FATCA reporting. FATCA is a global tax regime directed at U.S. tax residents who maintain accounts with foreign financial institutions. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values of A to M, with each letter representing a qualifying entity type. For example, FATCA exempt code D means a corporation whose stock is regularly traded on one or more established securities markets as described in Regulations section 1.1472-1(c)(1)(i). You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

  • The value is not a character between A and M.
  • You've set the taxClassification field to SMLLC.

address.firstLine: string (optional)

The value of this key is the first line of the customer's address.

The system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.secondLine: string (optional)

The value of this key is the second line of the customer's address.

This system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.city: string (optional)

The value of this key is the customer's city.

The system will discard this field if any of the following conditions are true:

  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

address.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

address.postalCode: string (optional)

The value of this key is the postal code of the customer's address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

address.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's country.

The system will discard this field if any of the following conditions are true:

Note: If you don't provide a value for this field, the system will try to derive the country code using address.stateOrProvince.

tinType: string (optional)

The value of this key is the customer's TIN type.

Supported values:

  • SSN
  • EIN

The system will discard this field if any of the following conditions are true:

  • The value is not supported.
  • You have already entered a valid value in the taxClassification field. In this case, the system will automatically set the value of tinType to the appropriate Tax ID type.
  • You've set the taxClassification field to SMLLC.

W-8BEN documentType

The following are W-8BEN properties.

referenceNumbers: string (optional)

The legal name of the beneficial owner of the account.

country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's country of citizenship.

The system will discard this field if any of the following conditions are true:

taxClassification: string (optional)

The value of this key is the tax classification of the customer.

The supported value is:

  • INDIVIDUAL

The system will discard this field if its value isn't one of the enumerated values above.

permanentAddress.firstLine: string (optional)

The value of this key is the first line of the customer's permanent residence address.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.secondLine: string (optional)

The value of this key is the second line of the customer's permanent residence address.

This system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.city: string (optional)

The value of this key is the customer's permanent residence city.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions is true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.

permanentAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's permanent residence address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

permanentAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince.

mailingAddress.firstLine: string (optional)

The value of this key is the first line of the customer's mailing address.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.secondLine: string (optional)

The value of this key is the second line of the customer's mailing address.

This system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.city: string (optional)

The value of this key is the customer's mailing city.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

mailingAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's mailing address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

mailingAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince.

dateOfBirth: string (optional)

For individuals, this key's value is the account owner's date of birth. It must be entered in the format MM/DD/YYYY.

The system will discard this value if you set the taxClassification field to SMLLC.

ftin: string (optional)

The value of this key is the customer's foreign tax identification number (FTIN).

ftinNotLegallyRequired: boolean (optional)

The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.

W-8BEN-E documentType

The following are W-8BEN-E properties.

referenceNumbers: string (optional)

The legal name of the US or foreign Disregarded Entity (DRE) owner.

The system will discard this value if you set the taxClassification field to SMLLC.

country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the country of incorporation or organization of the customer.

The system will discard this field if any of the following conditions are true:

taxClassification: string (optional)

The value of this key is the tax classification of the customer.

The supported value is:

  • CORPORATION
  • PARTNERSHIP
  • SIMPLE_TRUST
  • COMPLEX_TRUST
  • GRANTOR_TRUST
  • ESTATE
  • CENTRAL_BANK_OF_ISSUE
  • FOREIGN_GOVERNMENT_CONTROLLED_ENTITY
  • FOREIGN_GOVERNMENT_INTEGRAL_PART
  • TAX_EXEMPT_ORGANIZATION
  • PRIVATE_FOUNDATION
  • INTERNATIONAL_ORGANIZATION
  • DISREGARDED_ENTITY

The system will discard this field if its value isn't one of the enumerated values above.

permanentAddress.firstLine: string (optional)

The value of this key is the first line of the customer's permanent residence address.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.secondLine: string (optional)

The value of this key is the second line of the customer's permanent residence address.

This system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.city: string (optional)

The value of this key is the customer's permanent residence city.

The system will discard this field if any of the following conditions are true:

  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

permanentAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.

permanentAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's permanent residence address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The permanentAddress.country field is empty or invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

permanentAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from permanentAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince.

mailingAddress.firstLine: string (optional)

The value of this key is the first line of the customer's mailing address.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.secondLine: string (optional)

The value of this key is the second line of the customer's mailing address.

This system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.city: string (optional)

The value of this key is the customer's mailing city.

The system will discard this field if any of the following conditions are true:

  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

mailingAddress.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

  • The state code is invalid for the country. For example, if you set the address.country to US and the state to ZZ, the system would discard this field.
  • You've set the taxClassification field to SMLLC.

mailingAddress.postalCode: string (optional)

The value of this key is the postal code of the customer's mailing address.

U.S. Postal Codes can be in one of the following formats:

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will discard this field if any of the following conditions are true:

  • If the address is within the U.S., but the postal code is not a five or nine-digit string.
  • The mailingAddress.country field is empty or invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

mailingAddress.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.

The system will discard this field if any of the following conditions are true:

  • The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from mailingAddress.stateOrProvince.
  • You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince.

ftin: string (optional)

The value of this key is the customer's foreign tax identification number (FTIN).

ftinNotLegallyRequired: boolean (optional)

The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.

Updated about 1 month ago