REST API›Enterprise›Tax

POST

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

  • enterpriseId string required
    The enterprise ID to get a token for

    32 to 32 characters · matches ^[0-9a-zA-Z]{32}$

Body Params

object

Form W-8BEN submission payload.
  • e_delivery_consent boolean required
    Required 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_version string enum
    Set to 2021_OCT when submitting the official IRS Form W-8BEN; omit for substitute form
    2021_OCT
  • name string required
    Name of individual who is the beneficial owner (Line 1)

    at least 1 characters

  • country string enum required
    Country 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_address object required
    Required 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_line string required
      First line of the address

      at least 1 characters

    • second_line string
      Second line of the address
    • city string required
      City

      at least 1 characters

    • state_or_province string
      State or province (required 2-letter postal code when country is US or CA, e.g. WA or ON)

      at least 1 characters

    • postal_code string required
      Postal code

      at least 1 characters

    • country string enum required
      Country 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_address object
    Shared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.
    mailing_address object
    • first_line string
      First line of the address
    • second_line string
      Second line of the address
    • city string
      City
    • state_or_province string
      State or province (must be a 2-letter postal code when country is US or CA)
    • postal_code string
      Postal code
    • country string enum
      Country 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_tin string
    U.S. taxpayer identification number (SSN or ITIN), if required (Line 5)
  • ftin string
    Foreign tax identifying number (Line 6a; required unless ftin_not_legally_required is true)

    at least 1 characters

  • date_of_birth string date required
    Date of birth in YYYY-MM-DD format (Line 8)

    matches ^\d{4}-\d{2}-\d{2}$

  • reference_numbers string
    Reference number(s) (Line 7)
  • ftin_not_legally_required boolean
    Set to true if a foreign TIN is not legally required (Line 6b)
  • has_signed_and_certified boolean enum required
    Must be true to certify that the beneficial owner has signed and certified the W-8BEN under penalties of perjury (Part III)
    true
  • signature_timestamp string date-time required
    ISO 8601 timestamp when the form was signed
  • completed_for string enum
    Whether the form was completed for the ACCOUNT_HOLDER or REGARDED_OWNER
    ACCOUNT_HOLDERREGARDED_OWNER
  • treaty_claim_is_eligible boolean deprecated
    Deprecated: indicates whether the beneficial owner is claiming treaty benefits (prefer treaty_claim_country)
  • treaty_claim_country string enum
    Country 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_resident boolean
    Certifies residency in treaty_claim_country (substitute form only; omit when irs_version is 2021_OCT)
  • treaty_claim_type_of_income string enum
    Special rates and conditions: type of income (Line 10)
    BUSINESS_PROFITSDIVIDENDSINTERESTOTHER_INCOMEROYALTIES_MOTION_PICTURE_AND_TVROYALTIES_OTHER
  • treaty_claim_rate_of_withholding string
    Special rates and conditions: percentage rate of withholding (Line 10)
  • treaty_claim_article_paragraph string
    Special rates and conditions: treaty article and paragraph (Line 10)
  • treaty_claim_has_additional_conditions boolean
    Indicates whether additional conditions apply to the treaty claim
  • signature string required
    Electronic signature of the beneficial owner (Part III)

    at least 1 characters

Responses

201
201

Response Body

object

Response returned upon successful Form W-8BEN submission.
  • data object required
    Form W-8BEN data returned in submission and retrieval responses.
    data object
    • e_delivery_consent boolean required
      Required 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_version string enum
      IRS version of the submitted Form W-8BEN
      2021_OCT
    • name string
      Name of individual who is the beneficial owner
    • country string enum
      Country 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_address object
      Shared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.
      permanent_address object
      • first_line string
        First line of the address
      • second_line string
        Second line of the address
      • city string
        City
      • state_or_province string
        State or province (must be a 2-letter postal code when country is US or CA)
      • postal_code string
        Postal code
      • country string enum
        Country 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_address object
      Shared tax address object used across W-9, W-8BEN, W-8BEN-E, and Self-Certification.
      mailing_address object
      • Same shape as TaxAddress.
    • us_tin string
      Masked or unmasked U.S. taxpayer identification number
    • ftin string
      Masked or unmasked foreign tax identifying number
    • date_of_birth string
      Date of birth (YYYY-MM-DD)
    • reference_numbers string
      Reference number(s)
    • ftin_not_legally_required boolean
      Check if FTIN is not legally required
    • has_signed_and_certified boolean
      Indicates that the beneficial owner has signed and certified the W-8BEN
    • signature_timestamp string
      ISO 8601 timestamp when the form was signed
    • completed_for string enum
      Whether the form was completed for the ACCOUNT_HOLDER or REGARDED_OWNER
      ACCOUNT_HOLDERREGARDED_OWNER
    • treaty_claim_is_eligible boolean deprecated
      Indicates whether the beneficial owner is claiming treaty benefits
    • treaty_claim_country string enum
      Country 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_resident boolean
      Certifies residency in the treaty country
    • treaty_claim_type_of_income string enum
      Special rates and conditions: type of income
      BUSINESS_PROFITSDIVIDENDSINTERESTOTHER_INCOMEROYALTIES_MOTION_PICTURE_AND_TVROYALTIES_OTHER
    • treaty_claim_rate_of_withholding string
      Special rates and conditions: percentage rate of withholding
    • treaty_claim_article_paragraph string
      Special rates and conditions: treaty article and paragraph
    • treaty_claim_has_additional_conditions boolean
      Indicates whether additional conditions apply to the treaty claim
    • signature string
      Electronic signature of the beneficial owner
400
400

Response Body

object

  • error string required
    Error message describing the validation failure
  • message string required
    Details of why the request was rejected
  • issues array of objects
    Per-field validation failures when the request body fails schema validation
    issues object
    • <key> object
401
401

Response Body

object

  • error string
    Error name for the rejected request
  • message string required
    Reason the request was rejected
403
403

Response Body

object

  • error string
    Error message when the caller lacks permission on the enterprise
  • message string
    Explicit deny message
404
404

Response Body

object

  • error string required
    Error message indicating the resource was not found
  • message string required
    Which resource could not be found
409
409

Response Body

object

  • error string required
    Error message indicating a tax form was already submitted for the current tax year
  • message string required
    Details of the existing submission conflict
429
429

Response Body

object

  • error string required
    Error code emitted when the caller exceeds the rate limit
  • message string required
    How long to wait before retrying
500
500

Response Body

object

  • error string required