POST
Submit Form W-8BEN Tax Documentation
Submits IRS Form W-8BEN tax documentation data for an individual foreign beneficial owner associated with the specified enterprise. Note: This endpoint currently returns hardcoded mock responses for initial client integration.
Path Params
-
enterpriseIdstring requiredThe enterprise ID to get a token for
Body Params
object
Form W-8BEN submission payload.
-
e_delivery_consentboolean requiredRequired electronic delivery preference for tax documents (true = Confirm E-delivery, false = Continue with postal delivery). Clients can fetch the electronic delivery disclosure text via GET /api/identity-service/v1/agreements/taxEDeliveryConsent and must explicitly collect and pass the end user selection (do not default to true). -
irs_versionstring enumSet to 2021_OCT when submitting the official IRS Form W-8BEN; omit for substitute form2021_OCT -
namestring requiredName of individual who is the beneficial owner (Line 1) -
countrystring enum requiredCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD -
permanent_addressobject requiredRequired physical address for IRS tax form submissions (first_line, city, postal_code, and country required; 2-letter state_or_province required for US and CA).permanent_address object
-
first_linestring requiredFirst line of the address -
second_linestringSecond line of the address -
citystring requiredCity -
state_or_provincestringState or province (required 2-letter postal code when country is US or CA, e.g. WA or ON) -
postal_codestring requiredPostal code -
countrystring enum requiredCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD
-
-
mailing_addressobjectShared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.mailing_address object
-
first_linestringFirst line of the address -
second_linestringSecond line of the address -
citystringCity -
state_or_provincestringState or province (must be a 2-letter postal code when country is US or CA) -
postal_codestringPostal code -
countrystring enumCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD
-
-
us_tinstringU.S. taxpayer identification number (SSN or ITIN), if required (Line 5) -
ftinstringForeign tax identifying number (Line 6a; required unless ftin_not_legally_required is true) -
date_of_birthstring date requiredDate of birth in YYYY-MM-DD format (Line 8) -
reference_numbersstringReference number(s) (Line 7) -
ftin_not_legally_requiredbooleanSet to true if a foreign TIN is not legally required (Line 6b) -
has_signed_and_certifiedboolean enum requiredMust be true to certify that the beneficial owner has signed and certified the W-8BEN under penalties of perjury (Part III)true -
signature_timestampstring date-time requiredISO 8601 timestamp when the form was signed -
completed_forstring enumWhether the form was completed for the ACCOUNT_HOLDER or REGARDED_OWNERACCOUNT_HOLDERREGARDED_OWNER -
treaty_claim_is_eligibleboolean deprecatedDeprecated: indicates whether the beneficial owner is claiming treaty benefits (prefer treaty_claim_country) -
treaty_claim_countrystring enumCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD -
treaty_claim_i_certify_residentbooleanCertifies residency in treaty_claim_country (substitute form only; omit when irs_version is 2021_OCT) -
treaty_claim_type_of_incomestring enumSpecial rates and conditions: type of income (Line 10)BUSINESS_PROFITSDIVIDENDSINTERESTOTHER_INCOMEROYALTIES_MOTION_PICTURE_AND_TVROYALTIES_OTHER -
treaty_claim_rate_of_withholdingstringSpecial rates and conditions: percentage rate of withholding (Line 10) -
treaty_claim_article_paragraphstringSpecial rates and conditions: treaty article and paragraph (Line 10) -
treaty_claim_has_additional_conditionsbooleanIndicates whether additional conditions apply to the treaty claim -
signaturestring requiredElectronic signature of the beneficial owner (Part III)
Responses
201
201
Response Body
object
Response returned upon successful Form W-8BEN submission.
-
dataobject requiredForm W-8BEN data returned in submission and retrieval responses.data object
-
e_delivery_consentboolean requiredRequired electronic delivery preference for tax documents (true = Confirm E-delivery, false = Continue with postal delivery). Clients can fetch the electronic delivery disclosure text via GET /api/identity-service/v1/agreements/taxEDeliveryConsent and must explicitly collect and pass the end user selection (do not default to true). -
irs_versionstring enumIRS version of the submitted Form W-8BEN2021_OCT -
namestringName of individual who is the beneficial owner -
countrystring enumCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD -
permanent_addressobjectShared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.permanent_address object
-
first_linestringFirst line of the address -
second_linestringSecond line of the address -
citystringCity -
state_or_provincestringState or province (must be a 2-letter postal code when country is US or CA) -
postal_codestringPostal code -
countrystring enumCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD
-
-
mailing_addressobjectShared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.mailing_address object
- Same shape as
TaxAddress.
- Same shape as
-
us_tinstringMasked or unmasked U.S. taxpayer identification number -
ftinstringMasked or unmasked foreign tax identifying number -
date_of_birthstringDate of birth (YYYY-MM-DD) -
reference_numbersstringReference number(s) -
ftin_not_legally_requiredbooleanCheck if FTIN is not legally required -
has_signed_and_certifiedbooleanIndicates that the beneficial owner has signed and certified the W-8BEN -
signature_timestampstringISO 8601 timestamp when the form was signed -
completed_forstring enumWhether the form was completed for the ACCOUNT_HOLDER or REGARDED_OWNERACCOUNT_HOLDERREGARDED_OWNER -
treaty_claim_is_eligibleboolean deprecatedIndicates whether the beneficial owner is claiming treaty benefits -
treaty_claim_countrystring enumCountry identifier (ISO 3166-1 alpha-2 code, IRS-only code, or territory name).ADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESGSHSISJSKSLSMSNSOSRSSSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYEYTZAZMZWXKFQIPDXHQDQJQKQOCLQWQWZAKROTIRIASHMORE AND CARTIER ISLANDSBURMACORAL SEA ISLANDSEAST TIMORMIDWAY ISLANDSNAVASSA ISLANDPARACEL ISLANDSSPRATLY ISLANDSSVALBARD -
treaty_claim_i_certify_residentbooleanCertifies residency in the treaty country -
treaty_claim_type_of_incomestring enumSpecial rates and conditions: type of incomeBUSINESS_PROFITSDIVIDENDSINTERESTOTHER_INCOMEROYALTIES_MOTION_PICTURE_AND_TVROYALTIES_OTHER -
treaty_claim_rate_of_withholdingstringSpecial rates and conditions: percentage rate of withholding -
treaty_claim_article_paragraphstringSpecial rates and conditions: treaty article and paragraph -
treaty_claim_has_additional_conditionsbooleanIndicates whether additional conditions apply to the treaty claim -
signaturestringElectronic signature of the beneficial owner
-
400
400
Response Body
object
-
errorstring requiredError message describing the validation failure -
messagestring requiredDetails of why the request was rejected -
issuesarray of objectsPer-field validation failures when the request body fails schema validationissues object
-
<key>object
-
401
401
Response Body
object
-
errorstringError name for the rejected request -
messagestring requiredReason the request was rejected
403
403
Response Body
object
-
errorstringError message when the caller lacks permission on the enterprise -
messagestringExplicit deny message
404
404
Response Body
object
-
errorstring requiredError message indicating the resource was not found -
messagestring requiredWhich resource could not be found
409
409
Response Body
object
-
errorstring requiredError message indicating a tax form was already submitted for the current tax year -
messagestring requiredDetails of the existing submission conflict
429
429
Response Body
object
-
errorstring requiredError code emitted when the caller exceeds the rate limit -
messagestring requiredHow long to wait before retrying
500
500
Response Body
object
-
errorstring required